Authentication and Common Conventions

This page covers the conventions shared by all APIs, including the base URL, authentication, request and response formats, pagination, rate limiting, idempotency, and error handling. For parameters and examples of specific APIs, see API Overview and each API's own page.

Base URL

Authentication

All APIs use the same platform API key:

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

The Bearer prefix can be omitted (but don't)

Four variants, as tested:

Because the platform also accepts a bare token, a 200 response does not mean the client is configured correctly. Conversely, if a client returns 401, first check whether it omitted the entire Authorization header rather than suspecting the key itself. Always use the Bearer form.

If the API key is missing, incorrect, disabled, or does not belong to the current account, the API returns HTTP 401:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)",
    "type": "new_api_error"
  }
}

Note that code is an empty string. The platform does not populate code when authentication fails, so do not use whether code is empty to decide whether the request failed; rely on the HTTP status code instead. The request id in message can be extracted directly for filing a ticket.

This kind of authentication failure has the same structure across all APIs, and message includes the request identifier to make troubleshooting easier.

Response structure

The platform has three response structures; clients must check both the HTTP status code and the response body.

Model, text, image, video, and audio APIs

On success, the result object is returned directly; on failure, the API returns a non-2xx HTTP status with an error object:

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

Video task queries are the exception: when the task cannot be found, the API returns 400 and the response body is a top-level { code, message, data } structure (code is the string task_not_exist), not the error object above. See Error Codes and Troubleshooting for details. The values of code, type, and param vary by error type; when troubleshooting, rely primarily on message rather than matching fixed code text.

Asset library APIs

Both success and failure use a uniform structure:

{ "code": 0, "data": {}, "msg": "OK" }

{ "code": 401, "data": null, "msg": "API Key 无效或已失效" }

On failure, the HTTP status code matches code (400 / 401 / 404 / 429 / 502 / 503). An asset still under review is not an error; it appears as the status field in a 200 response (Processing / Active / Failed).

Pagination

List APIs such as asset groups and asset lists use uniform pagination parameters:

In the response, data.total is the total number of items, and data.page and data.page_size are the pagination parameters in effect for this request. Always use total to decide whether there is another page; do not use "the number of items returned this time".

Rate limiting and retries

Retry only on 429 and brief 5xx; 400, 401, 403, 404, and 409 indicate request or permission problems, and retrying will not help.

Idempotency and duplicate submissions

The platform does not provide an automatic idempotency key across APIs, so ensure on your side that each request is submitted only once:

• Before each user action, write a business record to your own database, then call the platform API;
• For both video task and asset submissions, save the ID returned by the platform and query whether it already exists before retrying;
• Do not resubmit an asset while it is Processing, or multiple assets will be created;
• Billing is based on tasks that are actually submitted successfully; duplicate submissions result in duplicate charges.

Recommended call order

GET  /v1/models                     选择模型，确认能力与可用性
POST /api/v1/materials/groups       需要素材时创建分组
POST /api/v1/materials/assets       提交图片，保存 asset_id
GET  /api/v1/materials/assets/{id}  轮询到 status 为 Active
POST /v1/video/generations          提交视频任务，用 asset://<id> 引用素材
GET  /v1/video/generations/{id}     轮询任务，读取结果或错误

Server-side integration recommendations

1. Set a reasonable timeout for each request, and distinguish between "timeout" and "user cancellation";
2. Retry 429 and brief 5xx with backoff a limited number of times, and return all other errors to the caller directly;
3. Save the business request number, model ID, asset ID, task ID, and the request identifier returned by the platform for troubleshooting;
4. Never write the API key into logs, error reports, frontend analytics, or screenshots;
5. For large files, prefer public HTTPS URLs from object storage or asset:// references from the asset library; do not stuff large files into the request body.

Next steps