文档 / 常见问题
常见问题与排错
账户、充值、API Key、模型调用、异步任务和结果链接的常见问题。
常见问题与排错#
本页汇总账户、充值、API Key、模型调用和异步任务最常见的问题。提交工单前，建议先记录请求时间、模型名、HTTP 状态码和任务 ID。
账户与充值#
为什么登录后看不到余额或订单？#
- 确认当前登录的是充值时使用的同一账号。
- 如果使用工作空间，检查当前是否切换到了正确的个人账户或工作空间。
- 支付成功但余额未更新时，刷新钱包页面并查看充值订单状态。
充值成功但额度没有到账怎么办？#
- 在 钱包 → 充值订单 查看订单是否为成功状态。
- 保留平台订单号和支付渠道订单号。
- 避免对同一订单重复支付。
- 长时间未到账时提交工单，并附订单号，不要上传完整银行卡或支付账户敏感信息。
为什么不能同时申请两笔发票？#
同一用户同时只能有一笔 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.aiOpenAI 兼容客户端如果要求填写到版本路径，可使用 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。
任务状态分别代表什么？#
| 状态 | 含义 |
|---|---|
pending | 已创建，等待执行 |
processing | 正在执行 |
completed | 已完成，可读取结果 |
failed | 已失败，读取 error |
任务一直 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、密码、私钥、支付账号或未经脱敏的业务数据。