端点参考 · 素材库

The guide below is in Chinese.

登记你有权使用的图片、视频或音频,等到 active 后把返回的 ref 放入生成请求。使用公网地址时可以先直接调用生成接口,收到 asset_required 后再登记,也可以预先登记反复使用的素材。

登记、查询、列表和删除素材本身不收取生成费用。生成任务按模型价格独立计费。

2. 注册素材

Shell command
curl "https://staging-dp.taotoken.io/v1/media/assets" \
  -H "Authorization: Bearer $TP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/my-photo.jpg", "asset_type": "image"}'
字段必填说明
url是必须是公网可拉取地址,不接受 base64 或二进制直传
asset_type是image / video / audio
name否素材名称,≤50 字符。只用于你自己认素材,不参与路由与计费。平台会把它下传给支持该字段的供货源;首尾空白会被去掉,去掉之后为空等同于没传

成功码是 201(不是 200),响应:

JSON
{
  "asset_id": "9f1c...",
  "ref": "tt-ref://9f1c...",
  "asset_type": "image",
  "status": "pending"
}

这一步是异步的:提交成功不代表可以立刻引用。status 此刻多半还是 pending,需要轮询到 active 才能在生成请求里使用这个句柄——引用一个还没 active 的句柄会被创建接口同步拒绝(400),不会让你等到轮询才发现。

官方协议里图片/视频/音频的 url 字段还支持 Base64 data URI 写法,但本平台的素材库注册只认公网 URL——传 Base64 会在注册时被拒绝。

平台素材可使用 tt-ref://<id>,也可使用 asset://<UUID>。火山官方预置素材使用火山提供的 asset:// ID,按火山兼容接口处理。

3. 查询素材状态

Shell command
curl "https://staging-dp.taotoken.io/v1/media/assets/ASSET_ID" -H "Authorization: Bearer $TP_API_KEY"

响应字段同注册接口(asset_id / ref / asset_type / status)。status 归一后共 6 个取值:

状态含义
pending排队中,还未开始处理
processing处理中
active可引用——只有这个状态能用于生成
failed处理失败;有原因时只提供可公开的业务说明或平台归纳,未知原因使用通用提示
expired已过期
deleted已删除

active 表示至少一家供货源最近一次查询时可用,不表示所有模型对应的登记都已就绪。另一模型所需的登记仍可能处理中;已就绪模型可以继续使用,不必等待其他登记。

请按需查询已有素材的状态,使用退避间隔并为本次等待设置有限时长。门户每次自动查询最多等待五分钟;显示“本次查询已暂停”后,可点击“继续查询”开启新一次有限查询,或稍后重新打开页面。该等待预算不改变素材状态,也不是上游处理承诺。不要因为另一模型尚未就绪重复注册、上传或更换句柄。处理耗时没有保证上限,继续查询也不保证最终成功。列表展示的是保存状态,不能代替单条状态查询。

门户页面的注册、单查和列表另提供 has_pending_bindings,用于在整体 active 时继续有限查询尚在处理的登记;该提示不代表指定模型可用,公共 API 的响应字段保持不变。API 调用方也应有限查询原有素材状态,目标模型是否可用仍以创建时的校验为准,避免反复创建生成任务来查询状态。

创建请求若仅因目标模型对应的登记仍在处理而不可路由,平台会在核对整批素材的所有权、同一账号和供货交集后,有限查询一次已有状态,再重读整批素材重新校验。查询成功不保证登记已经就绪;仍未就绪时不会提交生成,继续返回未就绪或暂不可用。已有可用登记的请求不等待其他账号;模型、规格、停用供货和账号隔离限制保持不变。

⚠ 出了结果之后的状态是「最近一次已知」,可能滞后于供应商侧。 同一份素材平台可能在多家供应商各登记一份:只要还有任何一家没出结果,本接口就会去问那一家;而已经出了结果的那一家,之后不再复查。因此当各家都出了结果,这份素材的状态就固定在最后一次已知值上——供应商侧此后若清理或失效了它,本接口与列表仍会显示 active,你要到创建生成任务时才会被上游拒绝。⇒ 把 active 读作「上次看到时可用」,⛔ 读作「此刻一定可用」。

上面这条只描述这个接口(GET https://staging-dp.taotoken.io/v1/media/assets/{asset_id})。若你走的是火山兼容的 /api/v3 形状,那条单查接口每次都会向供应商现取一次(见火山兼容接口 §5「素材下载地址」),不受这一条限制。

3a. 改素材名字

Code
PATCH https://staging-dp.taotoken.io/v1/media/assets/{asset_id}
Authorization: Bearer sk-…
Content-Type: application/json

{ "name": "我的形象照" }

只能改名字,不能换 url:一份素材在多家货源各存一份,而部分货源没有更新接口——放开换 url 会让同一个句柄在各家指向不同的内容,且不会有任何报错。要换内容请重新注册一条。

字段必填说明
name是≤50 字符。首尾空白会被去掉;去掉之后为空返回 422,不会被当成"清空名字"处理

成功返回 200 与该素材的最新视图(字段同查询接口)。

名字会尽力下传给各家货源:不支持改名的货源会被跳过(这是正常路径,不是错误),支持的那家若报错,平台不会因此让整次改名失败——你方的名字总是会被改掉。

4. 列出我的素材 / 删除素材

Code
GET https://staging-dp.taotoken.io/v1/media/assets?limit=50&offset=0     # limit 默认 50,服务端封顶 200
DELETE https://staging-dp.taotoken.io/v1/media/assets/{asset_id}          # 软删除,成功后 status 变为 deleted

列表项在基础字段之外多带 raw_url(注册时提交的原始 URL)与 created_at。查询/删除不属于你的 asset_id(或不存在的)统一返回 404——刻意不区分"不存在"与"不是你的",避免被用来试探他人素材是否存在。

注册时传过 name 的话,查询与列表都会回显它。

⚠ 删除是平台侧的「不再可引用」,⛔ 是供应商侧的删除。 删除成功后这个句柄立刻无法再用于生成,平台也不会再返回它;但素材本体仍留在供应商账号里——本平台当前不调用供应商的素材删除接口。如果你需要的是「把这份素材从供应商那里彻底清掉」,本接口目前做不到。

5. 在生成请求里引用素材

拿到 active 的句柄后,把它填进创建生成任务的 content 里对应的 url 位置:

JSON
{ "type": "image_url", "role": "first_frame", "image_url": { "url": "tt-ref://9f1c..." } }

句柄可以出现在 content 里任意 URL 位置,平台在路由到具体供货源时会自动改写成该供货源认得的引用格式,你不需要关心背后是哪家供应商。

6. 错误

/v1/media/assets 的错误详情在顶层 detail。

HTTP含义
200改名成功(§3a)
201注册成功
404素材不存在,或不属于你
422三类原因,靠 detail 字符串区分(⛔ 结构化字段,是纯文本):① asset_type 不在 image/video/audio 内,或请求体字段缺失/类型错;② 提交前的 URL 预校验没过,detail 形如 <code>: <说明>,code 取值 url_scheme_unsupported(非 http/https)/ url_host_not_public(主机名钉不住公网地址)/ url_unreachable(连不上或跳转过多)/ url_not_media_file(返回的不是媒体文件)/ url_type_mismatch(媒体类型与 asset_type 不符);③ 改名(§3a)时 name 去掉首尾空白后为空——不会被当成"清空名字"
502上游素材库上传失败
503目录里没有带素材库的供货源可用

注册失败的 502 保留 upstream_asset_upload_failed 标识及 detail 形状;只公开经受控结构识别、安全处理的业务说明或通用提示。明确的素材宽度过小类别可归纳为 Width is too small.,这是平台提示,不是上游逐字原话。不会公开供应商域名/身份、余额价格、Key、素材地址、客户输入、上游完整响应、RequestId 或异常栈。

failure_reason 只在素材整体为 failed 且有失败原因时提供;缺原因仍为 null。一家失败、另一家可用时整体为 active,不带失败原因。已有失败记录也在读取时执行安全处理。

在创建生成任务时引用素材可能收到的错误(这些码属于生成任务端点,不是素材库端点本身):

error.code含义你该做什么
asset_required当前可用的规格和路由要求媒体使用已登记的素材,公网 URL 无法用于这次请求先登记,等到 active 后引用返回的 ref。
asset_not_found句柄不存在,或不是你的素材检查句柄是否正确,必要时重新注册
asset_not_active素材存在,但整体或本次模型所需登记尚未就绪(整体也可能已是 active)查询原有素材状态并有限等待;失败或过期时检查原因,不要重复提交同一素材
asset_type_mismatch素材的真实类型与引用方式不符按素材类型引用:图片用 image_url、视频用 video_url、音频用 audio_url
asset_model_mismatch素材有可用绑定,但没有一条落在你请求的 model 下检查模型与素材的适用范围;不要把其他模型的处理中状态当作本模型稍后可用的保证
asset_supplier_mismatch同一次请求引用了多条素材,但没有一家货源能同时服务这些素材每次请求只引用一条素材,或改传公网 URL
asset_tier_conflict你的路由偏好与素材所在货源冲突调整路由偏好,或改传公网 URL
asset_supplier_unavailable引用的素材没有任何可路由的落地检查该素材状态;长期无可用绑定就重新上传

完整错误码 → 错误码。

下一步

用登记的图片创建首帧视频 · 创建生成任务