素材库

上传图片 / 视频 / 音频到素材库，在视频生成等接口中用 asset:// 引用

API 配置

保存后下方「Try It」面板会自动携带此 API Key 发送真实请求。

Base: api.xrtoken.net

视频生成等多模态接口可以用你上传到素材库的图片、视频、音频作为参考。素材只需上传一次，之后在任意请求里用 asset://<ASSET_ID> 引用即可，国内版和海外版格式完全一致。

相比每次请求都传一个 1 小时过期的预签名 URL，用素材库的好处：

永久引用，草稿保存再久也不会失效
同一张图可以跨多次生成复用，不用重复上传
素材可以复用到不同模型、不同任务

三步完成素材引用

1. 创建 AssetGroup（首次）

素材必须挂在一个 AssetGroup 下。一个用户可以有多个 Group。

curl -X POST https://api.xrtoken.ai/v1/asset-groups \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "Name": "我的素材库" }'

{ "GroupId": "asset-group-20260423-abc12", "Name": "我的素材库" }

拿到 GroupId 之后复用，不用每次都建新的。

2. 上传文件拿到 URL

两种方式：

方式 A — 走我们的 /v1/files 上传（推荐，OpenAI 兼容）：

curl -X POST https://api.xrtoken.ai/v1/files \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -F 'file=@/path/to/reference.png' \
  -F 'purpose=assistants'

{
  "id": "file-xxxxxxxx",
  "object": "file",
  "url": "https://xrtoken-storage-*.tos-*.bytepluses.com/uploads/<user>/<uuid>/reference.png?X-Tos-...",
  "bytes": 123456,
  "filename": "reference.png",
  "purpose": "assistants"
}

返回的 url 是 24h 签名 URL，下一步注册 Asset 用它当 URL 字段。如果 24h 内没注册完，可以重新 GET /v1/files/{id} 取一份新签名。

方式 B — 用你自己公网可访问的 URL（必须支持 GET 直接下载图/视频字节，不能是 HTML 页面）。

3. 注册为 Asset

curl -X POST https://api.xrtoken.ai/v1/assets \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":    "asset-group-20260423-abc12",
    "URL":        "<上一步的 URL>",
    "AssetType":  "Image",
    "Name":       "女主角参考图",
    "Moderation": { "Strategy": "Skip" }
  }'

AssetType 可取 Image / Video / Audio。Moderation.Strategy=Skip 跳过上游内容审查（仅海外版生效，国内忽略）。

{ "AssetId": "asset-20260423183015-xk4m2", ... }

4. 在视频生成里引用

把 image_url.url / video_url.url / audio_url.url 换成 asset://<AssetId> 即可，其它字段不变：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "把女主角放到这个场景里走过来" },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260423183015-xk4m2" }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": { "url": "asset://asset-20260419234137-txt6j" }
    }
  ],
  "duration": 5,
  "ratio": "16:9",
  "resolution": "720p"
}

可以引用 asset:// 的字段

只能放在 URL 类字段里：

字段	用途
`image_url.url`	参考图（`reference_image`）、首帧（`first_frame`）、尾帧（`last_frame`）
`video_url.url`	参考视频（`reference_video`，Seedance 2.0）
`audio_url.url`	参考音频（`reference_audio`，Seedance 2.0）

content[].text 里写 asset:// 没用，不会被解析。

混用规则

同一个请求里 asset:// 和普通 https:// URL 可以混用，比如一张参考图用素材库的、另一张临时图用签名 URL 的：

"content": [
  { "type": "text", "text": "..." },
  { "type": "image_url", "role": "reference_image",
    "image_url": { "url": "asset://asset-20260423183015-xk4m2" } },
  { "type": "image_url", "role": "reference_image",
    "image_url": { "url": "https://your-cdn.com/temp/xxx.png" } }
]

限制

单个请求里最多 10 个 asset 引用（上游 Ark 限制）
Asset 有 90 天 TTL（上游 Ark 限制），过期后 asset:// 会解析失败；长期素材在第 89 天重新注册即可
Asset 只对创建它的用户可见，用别人的 AssetId 会返回 403
asset:// 前缀不能用在 text 字段里 — 只能在 URL 字段里

第三方 SaaS 集成（多租户）

如果你是用一个 API key 服务自己的 N 个最终用户（典型 SaaS），加一个 external_user_id 参数（opaque 字符串，≤128 字符）就能把 AssetGroup 跟你的 end-user 一一绑定，互相隔离。

POST / PUT 接口：放 JSON body 里 "external_user_id": "your-end-user-id"
GET / DELETE 接口：query param ?external_user_id=your-end-user-id
不传 = 老行为（整个 API key 共享，第一方 web 用这条）

写入 AssetGroup（含 real-person 验证拿到的 group_id）时绑定到该 external_user_id；后续 list / get / update / delete 必须传同一个 external_user_id 才能看到。end-user A 的 external_user_id 看不到 end-user B 名下的 GroupId。

真人验证回调（stateless，无需后端开 webhook）

第三方调 POST /v1/asset-groups/validate-session 时可以多传两个字段：

{
  "callback_url": "https://your.app/face-done",
  "external_user_id": "end-user-42"
}

整个流程：

你拿到 H5Link（或 QRCodeDataURL），让 end-user 扫码完成 H5 人脸验证
火山把 end-user 浏览器跳转到我们的 /v1/asset-groups/face-callback（带签名 token + BytedToken），不是直接跳到你
我们 server 验签 → 调火山拿 GroupId → 写 user_asset_groups（带 external_user_id）→ HTTP 302 把 end-user 跳到你的 callback_url，URL 上 append：
- ?status=success&group_id=<新 GroupId>&external_user_id=<end-user-42>
- 或失败时 ?status=failed（无 group_id）
你的页面收到 redirect，按 query param 跟你的后端通知 end-user 即可

无需后端开 webhook，无需轮询，整个 callback 链路 stateless。callback_url 必须是 http(s) 且带 host，会保留你原有 query string（你的 tracking 参数会跟我们的 status / group_id 一起出现）。

不传 callback_url → 走第一方默认（跳回我们 dashboard），适合自己直接用 web playground。

开通前置条件

第三方接入真人验证需要先满足三个前置条件，不在公开 API 里自助开通，请联系商务申请：

trusted_creator tier：账号需开通可信创作者
企业认证：营业执照 / 公司主体核验通过
face-consent：人脸信息处理同意书（由我们后台代签 / 30 天有效）

申请通过后, 你的 API key 就能直接调 validate-session + 后续 CRUD。无需让 end-user 单独签 consent（同意书是 API key 持有者一次签了, 覆盖该 key 下所有 end-user）。