端点参考 · 素材库

素材库把一张图片/一段视频先注册成平台内部句柄 tt-ref://<id>，供后续创建生成任务时引用。平台自己不落地存储素材本体（本体留在上游供应商那边），句柄只是一层稳定的间接引用。

素材库是可选的一层：多数情况下图片/视频参考可以直接传公网 URL；只有当你的请求被路由到"要求素材必须先入库"的供货源时才需要这一步——具体哪次调用需要，接口会在你不这么做时明确报错（asset_required），不需要你自己预判。

1. 概述

状态	已上线
计费	素材库的注册/查询/列表/删除均不计费
信封	与生成任务端点不同——素材库执行在控制面，错误体是扁平的 {"detail": "..."} 结构，不是 {"error": {"message", "type"}}

2. 注册素材

POST https://intertoken.ai/v1/media/assets
Authorization: Bearer sk-…
Content-Type: application/json

{ "url": "https://example.com/my-photo.jpg", "asset_type": "image" }

字段	必填	说明
url	是	必须是公网可拉取地址，不接受 base64 或二进制直传
asset_type	是	image / video / audio
name	否	素材名称，≤50 字符。只用于你自己认素材，不参与路由与计费。平台会把它下传给支持该字段的供货源；首尾空白会被去掉，去掉之后为空等同于没传

成功码是 201（不是 200），响应：

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

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

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

⚠ asset://<ID>（上游自有素材句柄，目前特指火山官方预置素材）是另一回事，⛔ 不要和素材库混为一谈：它不经过这里的注册接口，直接在创建生成任务的 content[].url 位置传即可，网关原样透传给上游——仅路由到火山直连/太行供货源时上游才认得，传给其它货源会在生成阶段失败。

3. 查询素材状态

GET https://intertoken.ai/v1/media/assets/{asset_id}
Authorization: Bearer sk-…

响应字段同注册接口（asset_id / ref / asset_type / status）。status 归一后共 6 个取值：

状态	含义
pending	排队中，还未开始处理
processing	处理中
active	可引用——只有这个状态能用于生成
failed	处理失败（原因随上游透传，如人像/版权等被上游拒绝）
expired	已过期
deleted	已删除

多数素材几秒到二十几秒内可就绪，但这只是经验观察，不是平台承诺的上限——请轮询到终态，不要假设固定超时时间。

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

上面这条只描述这个接口（GET https://intertoken.ai/v1/media/assets/{asset_id}）。若你走的是火山兼容的 /api/v3 形状，那条单查接口每次都会向供应商现取一次（见《Seedance 系列模型接入指南》 §0a.4「素材的下载地址」），不受这一条限制。

3a. 改素材名字

PATCH https://intertoken.ai/v1/media/assets/{asset_id}
Authorization: Bearer sk-…
Content-Type: application/json

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

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

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

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

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

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

GET https://intertoken.ai/v1/media/assets?limit=50&offset=0     # limit 默认 50，服务端封顶 200
DELETE https://intertoken.ai/v1/media/assets/{asset_id}          # 软删除，成功后 status 变为 deleted

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

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

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

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

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

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

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

6. 错误

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	目录里没有带素材库的供货源可用

在创建生成任务时引用素材可能收到的错误（这些码属于生成任务端点，不是素材库端点本身）：

error.code	含义	你该做什么
asset_required	这条货源要求视频输入必须是素材库句柄，你传了公网 URL	先注册素材，等 active 后再引用
asset_not_found	句柄不存在，或不是你的素材	检查句柄是否正确，必要时重新注册
asset_not_active	素材存在但还没到 active（或已 failed）	继续轮询，或重新上传
asset_type_mismatch	素材的真实类型与引用方式不符	按素材类型引用：图片用 image_url、视频用 video_url、音频用 audio_url
asset_model_mismatch	素材有可用绑定，但没有一条落在你请求的 model 下	换成素材所属货源对应的模型，或改传公网 URL
asset_supplier_mismatch	同一次请求引用了多条素材，但没有一家货源能同时服务这些素材	每次请求只引用一条素材，或改传公网 URL
asset_tier_conflict	你的路由偏好与素材所在货源冲突	调整路由偏好，或改传公网 URL
asset_supplier_unavailable	引用的素材没有任何可路由的落地	检查该素材状态；长期无可用绑定就重新上传

完整错误码 → 错误码。