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 配置,实际额度以响应头为准。模板目录和模型目录分别计数。这里限制的是请求速率,不代表同时运行的生成任务数量。
重试建议:
429 或可重试的 5xx 时,可以按照 Retry-After 进行指数退避重试。