全部接口

按分组查阅方法和路径。不含平台管理接口。

会话

get /v1/me

当前身份与权限

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/system/status

读取当前组织生效的公告、维护状态与功能开关

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/system/capabilities

查看当前组织的模型配置与功能可用状态

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

模型

get /v1/models

可用模型与能力契约

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/models/{code}/price

模型销售价格

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`code`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/models/{code}

模型详情

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`code`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/quotes

费用报价（不扣费）

按照模型契约校验参数并计算销售价格；不会扣费或创建任务。请求体与 POST /v1/generations 相同。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`project_id`	body	anyOf	可选
`model_code`	body	string	必填
`prompt`	body	string	可选
`negative_prompt`	body	string	可选
`params`	body	object	可选
`references`	body	object[]	可选
`count`	body	integer	可选
`source`	body	studio\|canvas\|editor\|api\|pipeline\|mcp\|shots	可选
`idempotency_key`	body	string	可选
`expected_quote`	body	object	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

项目

post /v1/organization-invite-links/access/preview

预览网址邀请（登录会话）

Requires a fresh account session, a trusted Origin and the expected user identity. API keys are not accepted. The token is read from the JSON body and never cached.

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`Origin`	header	string	必填
`x-lashot-expected-user-id`	header	string	必填
`token`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/organization-invite-links/access/receipt

核对原邀请接受结果（登录会话）

Requires a fresh account session, a trusted Origin and the expected user identity. API keys are not accepted. The token is read from the JSON body and never cached.

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`Origin`	header	string	必填
`x-lashot-expected-user-id`	header	string	必填
`token`	body	string	必填
`expected_org_id`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/organization-invite-links/access/accept

确认加入受邀组织（登录会话）

Requires a fresh account session, a trusted Origin and the expected user identity. API keys are not accepted. The token is read from the JSON body and never cached.

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`Origin`	header	string	必填
`x-lashot-expected-user-id`	header	string	必填
`token`	body	string	必填
`expected_org_id`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/organization-invite-links/access/enter

进入已加入的组织（登录会话）

Requires a fresh account session, a trusted Origin and the expected user identity. API keys are not accepted. The token is read from the JSON body and never cached.

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`Origin`	header	string	必填
`x-lashot-expected-user-id`	header	string	必填
`token`	body	string	必填
`expected_org_id`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/organization-invite-links

列出组织网址邀请（管理员登录会话）

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/organization-invite-links

创建组织网址邀请（管理员登录会话）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`create_request_id`	body	string	必填
`max_uses`	body	integer	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/organization-invite-links/{id}/copy

复制组织网址邀请（管理员登录会话）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/organization-invite-links/{id}/revoke

撤销组织网址邀请（管理员登录会话）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/members

查询项目成员权限

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/member-candidates

查询可邀请的组织成员

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

put /v1/projects/{id}/members/{userId}

授予项目成员权限

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`userId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`access_revision`	body	string	必填
`idempotency_key`	body	string	必填
`permission`	body	read\|write\|admin	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/projects/{id}/members/{userId}

撤销项目成员权限

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`userId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`access_revision`	body	string	必填
`idempotency_key`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects

项目列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`include_archived`	query	true\|false	可选
`limit`	query	integer	可选
`cursor`	query	string	可选	上一页返回的 next_cursor

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects

创建项目

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`kind`	body	general\|drama\|commerce\|quickcut	可选
`aspect_ratio`	body	16:9\|9:16\|1:1\|4:3\|3:4\|21:9	可选
`style_preset`	body	string	可选
`settings`	body	object	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}

项目与资产统计

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/projects/{id}

使用 revision 更新项目

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	可选
`kind`	body	general\|drama\|commerce\|quickcut	可选
`aspect_ratio`	body	16:9\|9:16\|1:1\|4:3\|3:4\|21:9	可选
`style_preset`	body	anyOf	可选
`cover_asset_id`	body	anyOf	可选
`settings`	body	object	可选
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/projects/{id}

移入回收站（保留 30 天）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`204`	成功，无响应体
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/archive

归档项目

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/restore

恢复已归档项目

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/package/export

导出工作区文档和原始媒体

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/project-packages/inspect

校验并查看工作区项目包摘要

Raw application/zip body; maximum 256 MiB.

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/project-packages/import

将工作区项目包导入为新项目

Raw application/zip body. X-Import-Key must be a stable UUID; optional X-Project-Name is URL-encoded. Always creates a new project and never overwrites another project.

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/batches

列出项目批量任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/batches

创建批量任务草稿

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`id`	path	string	必填
`name`	body	string	必填
`csv`	body	string	可选
`data`	body	object[]	可选
`mapping`	body	object	可选
`concurrency`	body	integer	可选
`template_version_id`	body	string	可选
`template_id`	body	string	可选
`idempotency_key`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/batches/{id}

查看批量任务和行进度

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/batches/{id}/mapping

修改草稿列映射

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`id`	path	string	必填
`model_code`	body	string	可选
`model_column`	body	string	可选
`prompt_template`	body	string	可选
`variables`	body	object	可选
`params`	body	object	可选
`parameter_columns`	body	object	可选
`dependency_column`	body	string	可选
`dependency_role`	body	image\|first_frame\|last_frame\|style\|subject\|mask\|control\|audio\|video\|person\|top_garment\|bottom_garment	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/batches/{id}/precheck

预检并报价，不冻结余额

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/batches/{id}/start

启动已审核的批量任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`id`	path	string	必填
`digest`	body	string	必填

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/batches/{id}/cancel

取消待执行行并请求取消子任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/batches/{id}/retry

重新预检失败或取消行

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`id`	path	string	必填
`rows`	body	integer[]	可选
`corrections`	body	object[]	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/batches/{id}/errors.csv

下载错误行 CSV

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

文档

get /v1/projects/{id}/drama-plans

列出整剧策划方案

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/projects/{id}/drama-plans

保存原文并创建整剧策划

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`key`	body	string	必填
`source`	body	object	必填
`content`	body	object	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/projects/{id}/drama-plans/import

从文档提取剧本文字

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`bytes`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

get /v1/drama-plans/{id}

读取整剧策划与历史版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

patch /v1/drama-plans/{id}

保存策划并校验版本冲突

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	必填
`content`	body	object	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/drama-plans/{id}/publish

将分集方案建立为正式剧集

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/drama-plans/{id}/quote

获取模型策划任务报价

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`key`	body	string	必填
`revision`	body	integer	必填
`operation`	body	outline\|divide\|episode\|script	必填
`target`	body	string	可选
`instruction`	body	string	可选
`model`	body	string	必填
`params`	body	object	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/drama-plans/{id}/operations

提交已确认报价的策划任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`input`	body	object	必填
`quote`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

get /v1/drama-plans/{id}/operations/{key}

读取策划候选与生成回执

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`key`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/drama-plans/{id}/operations/{key}/resume

恢复原始策划生成请求

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`key`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/drama-plans/{id}/operations/{key}/review

采用或保留策划候选

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`key`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`accept`	body	boolean	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`413`	上传内容过大
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误
`502`	PROVIDER_ERROR
`503`	MODEL_UNAVAILABLE
`504`	PROVIDER_TIMEOUT

post /v1/projects/{id}/commands

提交文档命令（并发保护与回执）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`command_id`	body	string	必填	UUID
`type`	body	string	必填
`payload`	body	object	可选
`base_revision`	body	integer	必填
`idempotency_key`	body	string	必填	UUID

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/canvas

读取画布文档

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/timeline

读取时间线文档

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/scene3d

读取导演台文档

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/image

读取图片文档

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/image/versions

列出图片文档历史版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`cursor`	query	string	可选	上一页返回的 next_cursor
`limit`	query	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/image/versions/{versionId}

读取图片文档历史版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`versionId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/renders

创建 FFmpeg 时间线渲染任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`format`	body	mp4\|webm\|wav\|png_sequence	可选
`revision`	body	integer	可选
`video_bitrate`	body	integer	可选
`width`	body	integer	可选
`height`	body	integer	可选
`fps`	body	integer	可选
`idempotency_key`	body	string	可选

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/renders/{jobId}/cancel

取消尚未完成的时间线导出

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`jobId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/renders/{jobId}

读取时间线渲染任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`jobId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/exports

创建图片导出任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选
`page_id`	body	string	可选	UUID
`width`	body	integer	可选
`height`	body	integer	可选
`mode`	body	contain\|cover\|stretch	可选
`format`	body	png\|jpeg\|webp	可选
`idempotency_key`	body	string	可选

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/exports/{jobId}/retry

按冻结版本重试失败的图片导出

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`jobId`	path	string	必填

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/exports/{jobId}

读取图片导出任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`jobId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/templates

官方与团队模板

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`kind`	query	cover\|knowledge\|poster\|product\|quote\|event\|social\|story	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/templates

从图片文档保存模板

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`code`	body	string	可选
`name`	body	string	必填
`kind`	body	cover\|knowledge\|poster\|product\|quote\|event\|social\|story	必填
`document`	body	object	必填
`variables`	body	object[]	可选
`note`	body	string	可选
`publish_shared`	body	boolean	可选
`idempotency_key`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/templates/{id}

模板与最新版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/templates/{templateId}/apply

将模板应用到图片文档

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`templateId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`version`	body	integer	可选
`variables`	body	object	可选
`base_revision`	body	integer	必填
`command_id`	body	string	可选
`idempotency_key`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/products

商品列表

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/products

创建商品

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`title`	body	string	必填
`brand_color`	body	string	可选
`logo_asset_id`	body	anyOf	可选
`publish_shared`	body	boolean	可选
`idempotency_key`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/products/{id}

商品与 SKU 详情

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/products/{id}

更新商品

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	可选
`title`	body	string	可选
`brand_color`	body	string	可选
`logo_asset_id`	body	anyOf	可选
`publish_shared`	body	boolean	可选
`idempotency_key`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/products/{id}/skus

创建 SKU 与渠道尺寸预设

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`code`	body	string	必填
`title`	body	string	必填
`hero_asset_id`	body	anyOf	可选
`publish_shared`	body	boolean	可选
`idempotency_key`	body	string	可选
`channel_presets`	body	object[]	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/skus/{id}

更新 SKU

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`code`	body	string	可选
`title`	body	string	可选
`hero_asset_id`	body	anyOf	可选
`publish_shared`	body	boolean	可选
`idempotency_key`	body	string	可选
`channel_presets`	body	object[]	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/skus/{skuId}/exports

读取 SKU 导出进度和文件

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`skuId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/skus/{skuId}/apply

将 SKU 应用到模板并导出

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`skuId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`template_id`	body	string	必填
`version`	body	integer	可选
`variables`	body	object	可选
`base_revision`	body	integer	必填
`command_id`	body	string	可选
`idempotency_key`	body	string	可选
`export_channels`	body	boolean	可选
`layout_mode`	body	original\|adaptive	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/characters/{id}/reference-images

更新角色设计参考图并核对修订版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`reference_asset_ids`	body	string[]	必填
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/characters/{id}/versions

读取角色版本历史

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/characters/{id}/versions/{version}/restore

恢复角色为新版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`version`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/scenes/{id}/reference-images

更新场景设计参考图并核对修订版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`reference_asset_ids`	body	string[]	必填
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/scenes/{id}/versions

读取场景版本历史

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/scenes/{id}/versions/{version}/restore

恢复场景为新版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`version`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/props/{id}/reference-images

更新道具设计参考图并核对修订版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`reference_asset_ids`	body	string[]	必填
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/props/{id}/versions

读取道具版本历史

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/props/{id}/versions/{version}/restore

恢复道具为新版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`version`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/episodes/{id}/shot-order

调整剧集内的镜头顺序

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`shot_ids`	body	string[]	必填
`previous_ids`	body	string[]	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/characters/{id}

编辑角色卡

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	可选
`role`	body	string	可选
`appearance`	body	anyOf	可选
`styling`	body	anyOf	可选
`personality`	body	anyOf	可选
`final_prompt`	body	anyOf	可选
`revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/characters/{id}

删除角色资料

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选
`base_updated_at`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/scenes/{id}

编辑场景

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选
`location`	body	string	可选
`time_of_day`	body	anyOf	可选
`lighting`	body	anyOf	可选
`final_prompt`	body	anyOf	可选
`prompt`	body	anyOf	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/scenes/{id}

删除场景资料

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选
`base_updated_at`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/props/{id}

编辑道具

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`final_prompt`	body	anyOf	可选
`revision`	body	integer	可选
`name`	body	string	可选
`type`	body	string	可选
`prompt`	body	anyOf	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/props/{id}

删除道具资料

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选
`base_updated_at`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/shots/{id}

编辑镜头描述与提示词

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`character_ids`	body	string[]	可选
`prop_ids`	body	string[]	可选
`shot_type`	body	anyOf	可选
`angle`	body	anyOf	可选
`movement`	body	anyOf	可选
`atmosphere`	body	anyOf	可选
`bgm_prompt`	body	anyOf	可选
`sfx`	body	anyOf	可选
`first_frame_asset_id`	body	anyOf	可选
`last_frame_asset_id`	body	anyOf	可选
`scene_id`	body	anyOf	可选
`base_updated_at`	body	string	可选
`title`	body	string	可选
`description`	body	anyOf	可选
`duration_ms`	body	integer	可选
`image_prompt`	body	anyOf	可选
`video_prompt`	body	anyOf	可选
`dialogue`	body	object[]	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/shots/{id}

删除镜头及其版本记录

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选
`base_updated_at`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/episodes/{id}

删除剧集及其镜头记录

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	可选
`base_updated_at`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/characters/{id}/references

更新角色参考图片

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`reference_asset_ids`	body	string[]	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/drama

读取或创建项目短剧

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/projects/{projectId}/drama

更新短剧信息

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`title`	body	string	可选
`genre`	body	anyOf	可选
`style_preset`	body	anyOf	可选
`aspect_ratio`	body	string	可选
`language`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/episodes

剧集列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/episodes

创建剧集

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`title`	body	string	必填
`source_text`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/episodes/{episodeId}

更新剧集标题或原文

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`episodeId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`title`	body	string	可选
`source_text`	body	anyOf	可选
`script_text`	body	string	可选
`resolution`	body	720x1280\|1080x1920	可选
`base_updated_at`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/characters

角色列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/characters

创建角色与首个版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`role`	body	string	可选
`appearance`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/scenes

场景设定列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/scenes

创建场景设定

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`location`	body	string	必填
`time_of_day`	body	string	可选
`lighting`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/props

道具设定列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/props

创建道具设定

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`type`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/episodes/{episodeId}/shots

剧集分镜列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`episodeId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/episodes/{episodeId}/shots

创建分镜

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`episodeId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`title`	body	string	必填
`description`	body	string	可选
`duration_ms`	body	integer	可选
`scene_id`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/shots/{shotId}/takes

分镜候选版本列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`shotId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/shots/{shotId}/takes

记录分镜候选版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`shotId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`generation_id`	body	string	可选
`asset_version_id`	body	string	必填
`note`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/takes/{takeId}/accept

选定候选版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`takeId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/production/{operationId}/resume

恢复已确认但尚未启动的操作

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`operationId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/pipelines/{id}/quality-evidence

导出生成、对齐与审阅证据

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/quickcut/styles

列出制作视觉与字幕风格

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/production/quote

获取快剪制作操作报价

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`operation`	body	alignment\|research\|stock\|vision\|critic\|regenerate_scene\|revise_script	必填
`model_code`	body	string	必填
`scene_id`	body	string	可选
`frame_asset_version_id`	body	string	可选
`query`	body	string	可选
`media_kind`	body	image\|video	可选
`params`	body	object	可选
`idempotency_key`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/production

确认报价并启动制作操作

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`operation`	body	alignment\|research\|stock\|vision\|critic\|regenerate_scene\|revise_script	必填
`model_code`	body	string	必填
`scene_id`	body	string	可选
`frame_asset_version_id`	body	string	可选
`query`	body	string	可选
`media_kind`	body	image\|video	可选
`params`	body	object	可选
`idempotency_key`	body	string	必填
`quote_digest`	body	string	必填

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/pipelines/{id}/production/{operationId}

读取操作状态与归档结果

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`operationId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/production/{operationId}/accept

接纳已审阅的制作结果

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`operationId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/production/{operationId}/stock

确认图库素材许可并请求导入

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`operationId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`candidate_id`	body	string	必填
`scene_id`	body	string	必填
`license_accepted`	body	boolean	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/production/{operationId}/stock/attach

将已导入的图库素材应用到镜头

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`operationId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/resource-batches

准备角色形象或分镜版本的批量报价

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`kind`	body	character_image\|scene_image\|prop_image\|shot_take\|character_prompt\|scene_prompt\|prop_prompt\|shot_image_prompt\|shot_video_prompt	必填
`target_ids`	body	string[]	必填
`model_code`	body	string	必填
`params`	body	object	可选
`idempotency_key`	body	string	必填

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/retry-failed

仅为批次失败项创建重试流程

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`idempotency_key`	body	string	必填

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/steps/{n}/review

修改阶段结果并继续

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`n`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	必填
`changes`	body	object	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/skills/{id}/versions

读取指令版本历史

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/skills/{id}/fork

创建可编辑的团队指令副本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`body`	body	string	可选
`name`	body	string	可选
`attachments`	body	object	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/skills/{id}

保存指令新版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revision`	body	integer	必填
`body`	body	string	必填
`name`	body	string	可选
`attachments`	body	object	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/resource-generations

生成资源图片、镜头版本或配音

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`kind`	body	character_image\|scene_image\|prop_image\|shot_take\|speech\|character_prompt\|scene_prompt\|prop_prompt\|shot_image_prompt\|shot_video_prompt	必填
`target_id`	body	string	必填
`model_code`	body	string	必填
`prompt`	body	string	必填
`params`	body	object	可选
`references`	body	object[]	可选
`idempotency_key`	body	string	必填

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/quickcut/archetypes

沙箱快剪模板目录

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/skills

官方与团队技能目录

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/pipelines

项目工作流列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/pipelines

创建短剧或快剪工作流

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`kind`	body	drama\|quickcut\|commerce	可选
`params`	body	object	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/pipelines/{id}

工作流与步骤详情

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/prompt-review

应用已归档指令或保留流水线当前文本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`generation_id`	body	string	必填
`base`	body	anyOf	必填
`decision`	body	apply\|keep	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/pipelines/{id}/steps/{n}/quote

查看步骤报价

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`n`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/steps/{n}/approve-and-run

确认报价并排队执行短剧步骤

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`n`	path	string	必填

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/steps/{n}/execute

排队执行已确认步骤

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`n`	path	string	必填

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/pipelines/{id}/steps/{n}/prompt

构建步骤提示词（不调用模型）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`n`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/steps/{n}/confirm

确认付费步骤（不预扣）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`n`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/pipelines/{id}/steps/{n}/apply

应用已校验的工具调用

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`n`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`arguments`	body	object	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/voices

官方与团队音色目录

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/music-tracks

官方与团队配乐目录

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{projectId}/speech-segments

项目语音片段列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/speech-segments

创建语音片段（不调用付费服务）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`projectId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`text`	body	string	必填
`voice_id`	body	string	可选
`request_id`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/speech-segments/{id}/synthesize

生成沙箱 WAV（真实供应商未接入）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/shots/{shotId}/audio

分镜音频列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`shotId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/shots/{shotId}/audio

为分镜添加台词或旁白

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`shotId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`kind`	body	dialogue\|narration	必填
`text`	body	string	必填
`voice_id`	body	string	可选
`speech_segment_id`	body	string	可选
`asset_version_id`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/scene3d/captures

列出相机画面与临时预览

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/scene3d/captures

登记绑定场景版本的相机画面

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`id`	body	string	必填
`camera_id`	body	string	必填
`time_ms`	body	integer	必填
`asset_version_id`	body	string	必填
`kind`	body	image\|video	必填
`revision`	body	integer	必填
`source_stage_node_id`	body	string	可选
`view_camera`	body	object	可选
`orbit`	body	object	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/scene3d/panorama

将自有图片标记为全景

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`asset_version_id`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/stage/character-presets

导演台人物预设库

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/stage/pose-presets

导演台姿势预设库

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/episodes/{episodeId}/assemble

将选定版本与字幕写入时间线

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`episodeId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`shot_ids`	body	string[]	可选
`music_asset_version_id`	body	string	可选
`mode`	body	append\|replace	可选
`base_revision`	body	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

资产

get /v1/share/{token}

读取链接绑定的媒体版本

参数

名称	位置	类型		说明
`token`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/share/{token}/media

读取评审链接中的媒体内容

参数

名称	位置	类型		说明
`token`	path	string	必填

响应

状态码	说明
`200`	成功
`206`	OK
`304`	No content
`400`	请求参数不合法
`404`	资源不存在
`416`	No content
`422`	CONTENT_BLOCKED / PROVIDER_REJECTED
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/share/{token}/comments

通过审片链接添加批注

参数

名称	位置	类型		说明
`token`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`author_name`	body	string	必填
`body`	body	string	必填
`anchor`	body	object	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/share/{token}/approval

在允许访客批准时决定该版本

参数

名称	位置	类型		说明
`token`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`author_name`	body	string	必填
`decision`	body	approved\|changes_requested	必填
`version_hash`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{projectId}/shared-copies

复制组织目录素材到项目

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`projectId`	path	string	必填
`asset_ids`	body	string[]	必填
`idempotency_key`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/asset-versions/{versionId}/content

读取经鉴权的媒体内容

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`versionId`	path	string	必填

响应

状态码	说明
`200`	成功
`206`	OK
`304`	No content
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`416`	No content
`422`	CONTENT_BLOCKED / PROVIDER_REJECTED
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/assets/imports

资产导入任务列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`status`	query	pending\|downloading\|succeeded\|failed	可选
`limit`	query	integer	可选
`cursor`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/imports

从公开 HTTPS 地址导入资产

异步创建资产导入，返回 202。仅允许公开 HTTPS 地址；私网、回环、链路本地、CGNAT 与元数据地址返回 URL_BLOCKED。同一组织与 source_url 在 24 小时内复用已有导入。请求包含 url，可附 project_id、name。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`url`	body	string	必填
`project_id`	body	anyOf	可选
`name`	body	string	可选
`kind`	body	image\|video\|audio\|font\|subtitle\|model3d\|document\|bundle	可选

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/assets/imports/{id}

读取资产导入任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/multipart

创建或恢复分片上传

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`project_id`	body	string	必填
`mime`	body	string	必填
`byte_size`	body	integer	必填
`content_hash`	body	string	必填
`name`	body	string	必填
`idempotency_key`	body	string	必填

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/assets/multipart/{id}

恢复分片回执与完成状态

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/assets/multipart/{id}

取消分片上传并确认清理

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/multipart/{id}/parts

签发缺失分片上传地址

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`part_number`	body	integer	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/multipart/{id}/parts/complete

校验并保存分片回执

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`part_number`	body	integer	必填
`etag`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/multipart/{id}/complete

合并分片并校验文件

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/uploads

创建上传地址

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`request_id`	body	string	可选
`project_id`	body	anyOf	可选
`mime`	body	string	必填
`byte_size`	body	integer	必填

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/uploads/{intentId}/resume

恢复或续签同一次上传

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`intentId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/uploads/{intentId}/complete

完成上传并登记版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`intentId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	可选
`tags`	body	string[]	可选
`asset_id`	body	string	可选

响应

状态码	说明
`200`	成功
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`413`	上传内容过大
`415`	error
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/assets

资产列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`project_id`	query	string	可选
`kind`	query	string	可选
`tag`	query	string	可选
`trash`	query	true\|false	可选
`limit`	query	integer	可选
`cursor`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/assets/{id}

资产详情、版本与来源

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/assets/{id}

重命名或修改标签

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	可选
`tags`	body	string[]	可选
`current_version_id`	body	string	可选
`rights`	body	object	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/assets/{id}

将资产移入回收站

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`force`	query	true\|false	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/assets/{id}/url

获取临时下载地址

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`id`	path	string	必填
`version_id`	query	string	可选
`download`	query	true\|false	可选
`expires_in`	query	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/{id}/restore

从回收站恢复资产

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/assets/{id}/frames

提取首帧、尾帧或指定时间帧

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`position`	body	start\|end\|ms	必填
`at_ms`	body	integer	可选
`version_id`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/asset-versions/{versionId}/url

获取历史版本临时地址

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`versionId`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/fonts

可分发字体目录

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`project_id`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/fonts/subset

缓存字体字符子集

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`family`	body	string	必填
`text`	body	string	必填
`weight`	body	regular\|medium\|bold	可选
`project_id`	body	string	可选
`asset_version_id`	body	string	可选
`source_hash`	body	string	可选
`include_source`	body	boolean	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/review-targets

列出可审片版本与交付素材

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/shares

列出审片链接、批注和决定

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/shares

创建绑定版本的审片链接

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`target_type`	body	asset\|timeline\|render\|image_doc	必填
`target_id`	body	string	必填
`media_version_id`	body	string	可选
`title`	body	string	必填
`expires_at`	body	string	必填
`allow_comment`	body	boolean	可选
`allow_approval`	body	boolean	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/projects/{id}/shares/{shareId}

撤销审片链接或修改有效期

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`shareId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`revoke`	body	boolean	可选
`expires_at`	body	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/shares/{shareId}/approval

批准精确版本或要求修改

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`shareId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`author_name`	body	string	必填
`decision`	body	approved\|changes_requested	必填
`version_hash`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/projects/{id}/review-comments/{commentId}

解决或重新打开批注

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`commentId`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`resolved`	body	boolean	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/projects/{id}/deliveries

列出 ZIP 交付任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/projects/{id}/deliveries

打包已冻结的素材版本

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`version_ids`	body	string[]	必填
`idempotency_key`	body	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

生成

get /v1/generations

生成记录列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`project_id`	query	string	可选
`idempotency_key`	query	string	可选
`status`	query	string	可选
`limit`	query	integer	可选
`cursor`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/generations

创建生成任务（报价、预扣、排队）

工作台使用的统一请求格式。外部接入优先使用 /v1/images/generations 或 /v1/videos/generations。相同 Idempotency-Key 重放返回 200 和 replayed=true。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`project_id`	body	anyOf	可选
`model_code`	body	string	必填
`prompt`	body	string	可选
`negative_prompt`	body	string	可选
`params`	body	object	可选
`references`	body	object[]	可选
`count`	body	integer	可选
`source`	body	studio\|canvas\|editor\|api\|pipeline\|mcp\|shots	可选
`idempotency_key`	body	string	可选
`expected_quote`	body	object	可选

响应

状态码	说明
`200`	成功
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/generations/{id}

生成任务与输出详情

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/generations/{id}/cancel

取消生成（以供应商能力为准）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

任务

get /v1/jobs

任务列表

id 为生成 ID。只有 expand=outputs 时输出才包含签名地址。每页默认 20 条，最多 100 条。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`project_id`	query	string	可选
`status`	query	string	可选
`model`	query	string	可选
`key_id`	query	string	可选
`limit`	query	integer	可选
`cursor`	query	string	可选
`expand`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/jobs/{id}

按生成 ID 读取任务

对外 id 为生成 ID，也接受内部任务 ID。输出下载地址有效期 1 小时。费用仅包含 quoted、reserved、charged 销售金额。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/jobs/{id}/cancel

取消任务

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/jobs/{id}/events

任务事件流（SSE）

与 GET /v1/generations/:id/events 相同，路径 id 为生成 ID。收到事件后应重新读取任务，以服务端状态为准。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

图片

post /v1/images/generations

创建图片生成任务

传入 model、prompt、n、size、aspect_ratio、quality、seed 和 references。n 映射为 count，size/seed 传入 params；比例与质量须被模型契约支持。references 可用 asset_id、version_id、role；url 会导入资产，最多等待 20 秒。响应为 object=job，排队时 outputs 为空。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`model`	body	string	必填	模型代码，见模型目录
`prompt`	body	string	可选
`n`	body	integer	可选	输出张数，对应 count
`size`	body	string	可选	传入 params.size
`aspect_ratio`	body	string	可选	映射为契约 ratio 或 aspect_ratio
`quality`	body	string	可选	映射为契约 quality
`seed`	body	integer	可选	传入 params.seed
`references`	body	object[]	可选
`project_id`	body	anyOf	可选
`negative_prompt`	body	string	可选

响应

状态码	说明
`200`	成功
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/images/edits

创建图片编辑任务

请求体与图片生成相同，但至少一个 references[].role 必须为 image 或 mask，模型契约也必须支持该引用槽位。响应为任务视图。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`model`	body	string	必填	模型代码，见模型目录
`prompt`	body	string	可选
`n`	body	integer	可选	输出张数，对应 count
`size`	body	string	可选	传入 params.size
`aspect_ratio`	body	string	可选	映射为契约 ratio 或 aspect_ratio
`quality`	body	string	可选	映射为契约 quality
`seed`	body	integer	可选	传入 params.seed
`references`	body	object[]	可选
`project_id`	body	anyOf	可选
`negative_prompt`	body	string	可选

响应

状态码	说明
`200`	成功
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

视频

post /v1/videos/generations

创建视频生成任务

传入 model、prompt、duration_s、resolution、aspect_ratio、audio、seed 和 references。时长映射到契约 duration/duration_s，毫秒单位会换算；比例映射到 ratio/aspect_ratio。契约不支持 audio 时忽略并返回 warnings。引用 URL 导入最多等待 20 秒。响应为任务视图并附 warnings。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`model`	body	string	必填	模型代码，见模型目录
`prompt`	body	string	可选
`duration_s`	body	integer	可选	秒数，按契约 duration/duration_s 及单位换算
`resolution`	body	string	可选	传入 params.resolution
`aspect_ratio`	body	string	可选	映射为契约 ratio 或 aspect_ratio
`audio`	body	boolean	可选	模型支持时写入，否则返回 warnings
`seed`	body	integer	可选	传入 params.seed
`references`	body	object[]	可选
`project_id`	body	anyOf	可选
`negative_prompt`	body	string	可选

响应

状态码	说明
`200`	成功
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/videos/extensions

基于视频或尾帧续写视频

请求体与视频生成相同，但至少一个 references[].role 必须为 video 或 last_frame。模型不支持该引用槽位时返回 MODEL_CAPABILITY_UNSUPPORTED。响应包含任务与 warnings。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`model`	body	string	必填	模型代码，见模型目录
`prompt`	body	string	可选
`duration_s`	body	integer	可选	秒数，按契约 duration/duration_s 及单位换算
`resolution`	body	string	可选	传入 params.resolution
`aspect_ratio`	body	string	可选	映射为契约 ratio 或 aspect_ratio
`audio`	body	boolean	可选	模型支持时写入，否则返回 warnings
`seed`	body	integer	可选	传入 params.seed
`references`	body	object[]	可选
`project_id`	body	anyOf	可选
`negative_prompt`	body	string	可选

响应

状态码	说明
`200`	成功
`202`	已排队，请轮询任务或订阅事件
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`402`	余额或配额不足
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

事件

get /v1/events

组织事件流（SSE）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`project_id`	query	string	可选
`generation_id`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/generations/{id}/events

生成任务事件流（SSE）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

账务

get /v1/billing/balance

钱包余额、预扣与信用额度

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/billing/settings

低余额提醒阈值

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/billing/settings

设置低余额提醒

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`low_balance_threshold`	body	anyOf	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/billing/ledger

不可变账本（仅销售金额）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`type`	query	string	可选
`limit`	query	integer	可选
`cursor`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/billing/channels

可用充值渠道

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/billing/topups

充值订单列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`limit`	query	integer	可选
`cursor`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/billing/topups

创建充值订单

微信 Native 仅支持人民币且必须提供显式 Idempotency-Key。保留原键恢复同一订单；浏览器回跳不代表到账。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`amount`	body	anyOf	必填
`channel`	body	string	必填
`return_url`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/billing/topups/{id}

读取原充值订单和已保存的支付指令

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/billing/topups/{id}/refresh

查询支付通道并同步可信到账状态

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/billing/topups/{id}/resume

继续原微信支付订单并恢复支付指令

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/billing/topups/{id}/cancel

取消未支付充值订单

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`409`	版本、幂等键或操作状态冲突
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

用量

get /v1/usage/overview

请求与已结算消费概览

Defaults to the last seven days; maximum span is seven days, with inclusive UTC bounds. Failures are HTTP 4xx/5xx and failure_rate is null for zero requests. API keys see only their own calls and sales; project-bound keys additionally restrict attributed jobs and sales to their project. Unattributed calls remain limited to the requesting key.

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`from`	query	string	可选
`to`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/usage

调用用量与销售金额汇总

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`from`	query	string	可选
`to`	query	string	可选
`group_by`	query	string	可选
`project_id`	query	string	可选
`model_code`	query	string	可选
`key_id`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/usage/export.csv

导出 UTF-8 BOM 用量 CSV

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型
`from`	query	string	可选
`to`	query	string	可选
`group_by`	query	string	可选
`project_id`	query	string	可选
`model_code`	query	string	可选
`key_id`	query	string	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/usage/requests

组织 API 请求日志

默认最近 24 小时，单次最多查询 7 天；更长范围请导出。status 支持 2xx、4xx、5xx 或具体 HTTP 状态码。

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`key_id`	query	string	可选
`route`	query	string	可选
`status`	query	string	可选
`from`	query	string	可选
`to`	query	string	可选
`cursor`	query	string	可选	上一页返回的 next_cursor
`limit`	query	integer	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

API 密钥

get /v1/api-keys

API 密钥列表（不含哈希）

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/api-keys

创建 API 密钥（明文仅显示一次）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	必填
`scopes`	body	models:read\|generations:write\|generations:read\|assets:read\|assets:write\|projects:read\|projects:write\|commands:write\|billing:read\|webhooks:write[]	必填
`project_id`	body	anyOf	可选
`expires_in_days`	body	anyOf	可选
`ip_allowlist`	body	string[]	可选
`environment`	body	live\|test	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/api-keys/{id}

更新 API 密钥权限与限制

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`name`	body	string	可选
`ip_allowlist`	body	string[]	可选
`expires_in_days`	body	anyOf	可选
`scopes`	body	models:read\|generations:write\|generations:read\|assets:read\|assets:write\|projects:read\|projects:write\|commands:write\|billing:read\|webhooks:write[]	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/api-keys/{id}

撤销 API 密钥

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`204`	成功，无响应体
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

Webhook

get /v1/webhooks

Webhook 端点列表

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`limit`	query	integer	可选
`cursor`	query	string	可选	上一页返回的 next_cursor

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/webhooks

创建 Webhook（密钥仅显示一次）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`url`	body	string	必填
`events`	body	job.succeeded\|job.failed\|job.needs_reconciliation\|job.cancelled\|asset.imported\|balance.low\|review.comment.added\|review.approval.added[]	必填
`description`	body	string	可选

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/webhooks/events

可订阅事件目录

请求头带 x-api-key，或使用已登录会话。

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/webhooks/{id}

Webhook 端点详情

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

patch /v1/webhooks/{id}

更新 Webhook 端点

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`Idempotency-Key`	header	string	可选	24 小时内同键同体重放响应；不同请求体返回 409 IDEMPOTENCY_MISMATCH，处理中返回 409 IDEMPOTENCY_IN_FLIGHT 和 Retry-After: 1。未传键时创建/扣费请求按摘要在 10 分钟内去重。
`url`	body	string	可选
`events`	body	job.succeeded\|job.failed\|job.needs_reconciliation\|job.cancelled\|asset.imported\|balance.low\|review.comment.added\|review.approval.added[]	可选
`description`	body	anyOf	可选
`status`	body	active\|paused	可选

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

delete /v1/webhooks/{id}

删除 Webhook 端点

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`204`	成功，无响应体
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/webhooks/{id}/rotate-secret

轮换 Webhook 密钥

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/webhooks/{id}/test

发送 ping 测试投递

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填

响应

状态码	说明
`201`	创建成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

get /v1/webhooks/{id}/deliveries

Webhook 投递记录

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`status`	query	pending\|succeeded\|failed	可选
`limit`	query	integer	可选
`cursor`	query	string	可选	上一页返回的 next_cursor

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

post /v1/webhooks/{id}/deliveries/{did}/redeliver

重发一次 Webhook 投递

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`id`	path	string	必填
`did`	path	string	必填

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误

审计

get /v1/audit

组织审计日志（已脱敏）

请求头带 x-api-key，或使用已登录会话。

参数

名称	位置	类型		说明
`actions`	query	string	可选	逗号分隔的动作或前缀，例如 auth、webhook.create
`from`	query	string	可选	仅返回 created_at >= from 的记录
`limit`	query	integer	可选
`cursor`	query	string	可选	上一页返回的 next_cursor

响应

状态码	说明
`200`	成功
`400`	请求参数不合法
`401`	未登录或 API 密钥无效
`403`	权限、范围或模型未开放
`404`	资源不存在
`429`	请求限流，请遵循 Retry-After
`500`	服务内部错误