NearToken

外观

请求与错误 ​

错误格式 ​

接口错误使用统一 JSON 结构。message 给人看，type 和 code 给程序判断：

json
{
  "error": {
    "message": "请求参数无效",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "model"
  }
}

部分兼容响应会省略 param，客户端不要依赖字段顺序。

状态码 ​

状态码含义处理
400参数缺失或取值不符合要求按文档修正后重提
401令牌缺失、格式错误或已失效检查 Authorization / x-api-key / x-goog-api-key
402余额不足充值或换有余额的令牌
403令牌无权访问该模型或分组在控制台调整分组与模型限制
404模型、任务或结果不存在用清单里的模型名和原任务 ID 重试
408等待超时继续查询原任务，不要立刻重新创建
409与当前任务状态冲突等任务进入终态再操作
422请求体无法通过字段校验检查 JSON 类型、字段名、取值范围
429请求频率或并发超限按 Retry-After 等待后重试
500服务处理异常稍后重试，保留请求 ID
502 / 503上游暂时不可用稍后重试，不要连续创建相同任务

任务状态 ​

视频、图片任务与 Suno 音乐都是异步任务，HTTP 200 只代表创建成功。

视频：queued → in_progress → completed，终态可能是 failed 或 cancelled。只有 completed 才能请求 /v1/videos/{task_id}/content。

json
{
  "id": "task_01J00000000000000000000",
  "object": "video",
  "model": "veo-3.1",
  "status": "failed",
  "error": {"code": "generation_failed", "message": "视频生成失败"}
}

Suno 音乐：QUEUED → SUBMITTING → IN_PROGRESS → SUCCESS，失败为 FAILURE 并带 fail_reason。歌词任务不经过 IN_PROGRESS。

重试 ​

  • 参数错误、鉴权失败、权限不足、余额不足：不要重试，先改请求或账户。
  • 已经拿到任务 ID：只查询这个 ID，不要重复提交同一请求。
  • 收到 408 / 502 / 503：先查任务状态或控制台使用日志，再决定是否重试。
  • 收到 429：按 Retry-After 等待；没有该响应头时用指数退避。
  • 图片、视频、音乐都可能产生实际费用，超时后先确认是否已经生成再重提。

反馈 ​

保留响应头里的请求 ID、任务 ID、公开模型名和状态码，附上脱敏后的请求参数。不要提交令牌、完整媒体内容或调试日志。

NearToken