API v1

登记素材

POST/v1/assets

需要 service.use 权限。

查看 Markdown
  • 在请求头 Authorization: Bearer 后面放 API 密钥;API 密钥需要 service.use 权限。
  • 必须带 Idempotency-Key;相同请求重放原响应,不同请求被拒绝。
  • 接受后异步获取并校验,按 Location 查询状态。
  • 只有 active 素材可以在生成请求里用 asset:// 引用。

请求头

#Authorizationstring必填

Bearer 加一个空格和 API 密钥。缺失或无效时返回 401 authentication_failed。

#Content-Typestring必填

请求体是 JSON:application/json。

#X-Request-IDstring

你自己的请求标识。无效或重复的值会被替换,最终值在响应头 X-Request-ID 返回。

#Idempotency-Keystring必填

每个新请求生成一个新值并保存,以字母或数字开头。结果不明时用同一个键和原请求体重试,会返回原响应;同一个键配不同的请求体返回 409 idempotency_conflict。键按团队区分,不按 API 密钥区分。

长度8–128字符A–Z a–z 0–9 . _ : -

请求体application/json · 必填

请求体只接受下列字段,其他字段会被拒绝。

#urlstring必填

公开 HTTPS 素材来源地址,UTF-8 编码最多 2048 字节,不得含用户信息;获取策略也拒绝不安全目的地。

长度9–2048格式https://
#media_typestring必填

媒体类型。

可选imageaudiovideo
#modelstring必填

本次使用的模型标识。

dreamina-seedance-2-0-260128Seedance 2.0
dreamina-seedance-2-0-fast-260128Seedance 2.0 Fast
dreamina-seedance-2-0-mini-260615Seedance 2.0 Mini
#namestring

可选显示名称;不含控制符、行段分隔符或双向文本控制符。

长度1–64

返回HTTP 202

素材接入已接受,请按 Location 查询状态。

#asset_idstring必填

平台素材标识。

长度36–36格式ast- 加 32 位十六进制
#statusstring必填

当前状态,具体含义见对应取值。

固定为processing

响应头

#X-Request-IDstring必填

本次请求的标识:你提供的有效值,或替换后的值。

#Cache-Controlstring必填

响应不应被缓存。

#Locationstring必填

已接受对象的规范查询路径。

状态码

每个 error.code 的处理办法见「错误码」。

状态码说明与 error.code
202素材接入已接受,请按 Location 查询状态。
响应头Cache-ControlLocation
400请求无效,或素材来源地址不符合 HTTPS 获取策略。
401API 密钥缺失或无效。
响应头WWW-Authenticate
403当前 API Key 缺少 service.use 权限。
409本团队该操作键已用于不同的规范素材登记请求。
410原接受操作的精确重放响应已过期,不会再次创建。
429团队存储字节额度或素材接入容量不允许接受此素材。
503服务暂时不可用。