Growth Studio OpenAPI接入文档 · Errors and Retries

错误响应

接口调用失败时使用标准 HTTP 状态码,并返回统一错误结构:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request contains invalid video or media parameters.",
    "retryable": false,
    "details": {}
  },
  "request_id": "request_abc123"
}
字段 类型 说明
error.code string 稳定错误码,调用方应优先根据该字段处理
error.message string 面向开发者的错误描述,不应通过字符串匹配编写业务逻辑
error.retryable boolean 条件不变时是否适合重试
error.details object 附加信息,没有时为空对象
request_id string 请求追踪标识

常见错误码:

HTTP error.code retryable 说明
400 INVALID_REQUEST false JSON、视频参数、图片 URL 或查询参数不合法
400 INVALID_CURSOR false cursor 无效、被修改或与当前筛选条件不匹配
400 TEMPLATE_NOT_FOUND false 模板不存在或已停用,重新获取模板目录
400 MODEL_NOT_FOUND false 模型不在当前开放目录中,重新获取模型目录
401 INVALID_API_KEY false API Key 缺失、错误或不可用
402 INSUFFICIENT_BALANCE false 工作空间钱包余额不足
403 WORKSPACE_ACCESS_DENIED false API Key 对应用户已失去工作空间访问权限
404 VIDEO_NOT_FOUND false 视频不存在或不属于当前账号和工作空间
404 IMAGE_TASK_NOT_FOUND false 套图任务不存在、不可访问或不属于支持的套图类型
409 VIDEO_EDIT_UNAVAILABLE false 视频当前不支持编辑或已有编辑任务正在进行
409 MODEL_CATALOG_VERSION_STALE false 提交的模型目录版本已过期,更新目录后重新构造请求
409 TEMPLATE_PRICE_CHANGED false 提交的 expected_price 与当前模板价格不一致,重新获取模板列表的 pricing 计价后提交
413 PAYLOAD_TOO_LARGE false 上传图片超过 20 MiB,或裂变/套图 JSON 请求体超过 1 MiB
415 UNSUPPORTED_MEDIA_TYPE false 上传内容不是受支持的 JPEG、PNG 或 WebP 图片
422 PRODUCT_FETCH_FAILED false 商品链接未取得可用信息,可改为手填商品
422 MEDIA_PROCESSING_FAILED false 图片处理或内容审核未通过,可能涉及商品文案、脚本或图片
422 TEMPLATE_PRICE_UNAVAILABLE false 模板无法按所选参数计价,调整参数或更换模板
429 CONCURRENCY_LIMIT_EXCEEDED true 同时运行的任务数超过额度,等待已有任务结束
429 RATE_LIMIT_EXCEEDED true 超过当前接口调用额度
500 INTERNAL_ERROR 以响应为准 服务内部异常
503 UPLOAD_FAILED true 图片上传失败,可以稍后重试
503 TEMPLATE_CATALOG_UNAVAILABLE true 模板目录或模板执行规格暂不可用
503 MODEL_CATALOG_UNAVAILABLE true 模型目录暂不可用
503 SERVICE_UNAVAILABLE true 依赖服务暂时不可用

商品套图即使部分或全部图片失败,也可能以 HTTP 200 返回 status=completed;该状态表示结算完成,应检查每张图片的状态。视频受理后的失败同样通过查询响应体体现,不会改变先前的 202 创建响应。

限流与重试

限流按照“API Key + 接口类型”分别计算,并在多个服务实例间共享。具体额度以正式环境分配方案和响应头为准。

正常响应可能包含:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1784700000

超过额度时返回:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "The API key has exceeded the request rate limit.",
    "retryable": true,
    "details": {
      "limit": 1000,
      "window_seconds": 60
    }
  },
  "request_id": "request_abc123"
}
接口 额度 限流维度
POST /openapi/v1/image/upload 1,000 次/分钟 API Key + 接口
POST /openapi/v1/videos 200 次/分钟 API Key + 接口
POST /openapi/v1/template/videos/generations 与商品视频共享 200 次/分钟 API Key + 视频创建操作
POST /openapi/v1/template/generate 与商品视频共享 200 次/分钟 API Key + 视频创建操作
POST /openapi/v1/variation/videos/generations 与商品视频共享 200 次/分钟 API Key + 视频创建操作
POST /openapi/v1/creation/videos/generations 与商品视频共享 200 次/分钟 API Key + 视频创建操作
POST /openapi/v1/product-suite/images/generations 200 次/分钟,与普通图片生成共享 API Key + 图片创建操作
GET /openapi/v1/product-suite/images/generations/:task_id 8,000 次/分钟,与普通图片任务查询共享 API Key + 图片任务查询操作
GET /openapi/v1/video-templates 4,000 次/分钟 API Key + 模板目录查询操作
GET /openapi/v1/template/list、GET /openapi/v1/template/tags 与模板目录查询共享 4,000 次/分钟 API Key + 模板目录查询操作
GET /openapi/v1/models 4,000 次/分钟 API Key + 模型目录查询操作
GET /openapi/v1/images 4,000 次/分钟 API Key + 图片列表查询操作
GET /openapi/v1/videos 4,000 次/分钟 API Key + 接口
GET /openapi/v1/videos/:video_id 8,000 次/分钟 API Key + 接口

表中为本次核对的 master 配置,实际额度以响应头为准。模板目录和模型目录分别计数。这里限制的是请求速率,不代表同时运行的生成任务数量。

重试建议: