常见问题与排错

常见问题与排错#

本页汇总账户、充值、API Key、模型调用和异步任务最常见的问题。提交工单前，建议先记录请求时间、模型名、HTTP 状态码和任务 ID。

账户与充值#

为什么登录后看不到余额或订单？#

• 确认当前登录的是充值时使用的同一账号。
• 如果使用工作空间，检查当前是否切换到了正确的个人账户或工作空间。
• 支付成功但余额未更新时，刷新钱包页面并查看充值订单状态。

充值成功但额度没有到账怎么办？#

1. 在 钱包 → 充值订单 查看订单是否为成功状态。
2. 保留平台订单号和支付渠道订单号。
3. 避免对同一订单重复支付。
4. 长时间未到账时提交工单，并附订单号，不要上传完整银行卡或支付账户敏感信息。

为什么不能同时申请两笔发票？#

同一用户同时只能有一笔 pending 或 processing 状态的开票申请。当前申请开具完成或被拒绝后，才能提交下一笔申请。

API Key#

如何创建 Key？#

进入用户控制台的 API Keys 页面，点击创建并按需要设置名称、权限和额度限制。建议为不同项目、环境和客户端分别创建 Key。

Key 为什么显示不完整？#

为保护凭证，控制台列表通常只显示脱敏值。创建时应立即保存完整 Key；如果已经丢失，建议删除旧 Key 并重新创建，不要尝试从日志或数据库页面找回明文。

401 Unauthorized#

常见原因：

• Authorization 请求头缺失。
• Bearer 格式错误，正确格式是 Authorization: Bearer YOUR_API_KEY。
• Key 前后带有空格或换行。
• Key 已被删除、禁用或超过自身额度限制。
• Claude 原生 SDK 使用了错误的鉴权变量。

403 Forbidden#

通常表示 Key 或账号没有目标模型权限。检查 Key 的模型限制、用户分组和模型是否仍在可用列表中。

Key 泄露怎么办？#

立即在控制台删除或禁用该 Key，然后创建新 Key并更新服务端环境变量。不要只修改代码仓库中的值，因为旧 Key 仍可被继续使用。

模型与请求#

应该使用哪个 Base URL？#

默认使用：

https://api.apimax.ai

OpenAI 兼容客户端如果要求填写到版本路径，可使用 https://api.apimax.ai/v1。Claude Code 等要求根地址的工具不要额外拼接 /v1/messages。

模型名从哪里获取？#

以 APIMAX 控制台模型列表和具体模型文档为准。不要照搬其他平台的模型 ID；同一系列在不同平台可能使用不同名称。

404 Not Found#

• 检查 Base URL 和接口路径是否重复拼接了 /v1。
• 图像异步接口是 /v1/images/async-generations，不是其他平台的同名路径。
• 统一任务查询接口是 /v1/tasks/{id}。

400 参数错误#

• 检查必填字段和 JSON 语法。
• 不同模型支持的分辨率、时长、参考图数量和采样参数不同。
• 显式关闭客户端的高级参数，再用最小请求验证。
• 0、false 等显式值不要随意删除，它们可能有业务含义。

429 Too Many Requests#

表示请求频率、并发数或上游资源达到限制。降低并发并使用指数退避；异步任务提交后不要高频轮询。持续需要更高并发时，请根据实际业务联系支持。

异步任务#

提交成功为什么没有立即返回图片或视频？#

异步接口先返回任务 ID。继续调用 GET /v1/tasks/{id}，直到状态变为 completed 或 failed。

任务状态分别代表什么？#

任务一直 processing#

• 图像通常需要几十秒，视频和音乐可能需要数分钟。
• 使用合理轮询间隔，避免每秒多次查询。
• 超过模型文档建议时长后，记录任务 ID 并查看任务记录。
• 不要因为客户端超时就立即重复提交，先确认原任务终态，避免重复计费。

failed 后是否会退款？#

网关执行失败时会按任务计费规则进行退款或差额结算。最终以账户用量日志和余额记录为准；如记录异常，请提供任务 ID 联系支持。

结果 URL 打不开#

• URL 可能已经过期，任务响应中的 url_expires_at 会给出过期时间。
• 任务完成后应尽快下载并转存。
• 检查本机网络是否能访问对应对象存储或 CDN 域名。

错误处理#

upstream_error#

上游拒绝了请求，常见于参数不兼容、内容安全策略或输入文件问题。查看 error.upstream.code 和脱敏后的 message，修改请求后再试。

upstream_unavailable#

上游暂时不可用或重试耗尽。可等待后重试，不要立即高并发重复提交。

storage_error#

结果转存失败。稍后重试；如果反复出现，保留任务 ID 联系支持。

insufficient_quota#

余额或 Key 可用额度不足。检查钱包余额、订阅额度、Key 限额和当前工作空间。

提交工单前准备#

请提供：

• 任务 ID 或请求时间。
• 使用的模型名和接口路径。
• HTTP 状态码。
• 完整错误对象的脱敏版本。
• 是否稳定复现，以及最小复现请求。

不要提供完整 API Key、密码、私钥、支付账号或未经脱敏的业务数据。