05 素材库 (Asset Library)

上传 / 管理可复用的素材(图片、视频、音频), 在视频生成请求里用 asset:// 协议引用。

用途

避免重复上传: 同一张参考图要在 10 个任务里用 → 上传一次, 用 10 次
私有素材保护: 不想把素材放公网 URL → 用素材库 + 内部引用
批量管理: 按"组"组织素材, 便于清理

数据模型

SeedanceAssetGroup (组)
  ├─ id: <upstream group id>     ← 由上游分配
  ├─ user_id: 12345              ← 所有权绑定用户(本地记录)
  ├─ name: "我的猫照片"
  ├─ group_type: "" | "AIGC"     ← 真人认证生成的组类型 = "AIGC"
  ├─ source: "manual" | "visual_validate"
  └─ assets: [
       SeedanceAsset (素材)
         ├─ id: <upstream asset id>
         ├─ user_id, group_id
         ├─ name
         └─ asset_type: "Image" | "Video" | "Audio"
     ]

Endpoint 总表

操作	Method	URL
创建组	POST	`/v1/seedance/asset-groups`
列出我的所有组	GET	`/v1/seedance/asset-groups`
上传素材	POST	`/v1/seedance/assets`
查素材详情	GET	`/v1/seedance/assets/{asset_id}`
更新素材 URL	PATCH	`/v1/seedance/assets/{asset_id}`
删除素材	DELETE	`/v1/seedance/assets/{asset_id}`

所有 endpoint 都要 Authorization: Bearer sk-xxx。

创建组

bash

curl -X POST https://www.dianlitoken.com/v1/seedance/asset-groups \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的猫照片",
    "description": "做猫视频的素材",
    "group_type": ""
  }'

请求字段:

字段	必填	说明
`name`	必填	组名
`description`	选填	描述(仅本地记录,不暴露上游)
`group_type`	选填	通常留空。 `"AIGC"` 是真人认证组的类型,平台自动用

json

{
  "id": "<upstream-group-id>",
  "name": "我的猫照片",
  "group_type": ""
}

返回只有 id / name / group_type。 description 仅本地保存,不在返回里。

列出我的所有组

bash

curl https://www.dianlitoken.com/v1/seedance/asset-groups \
  -H "Authorization: Bearer sk-xxx"

json

{
  "data": [
    {
      "id": "<group-id-1>",
      "name": "我的猫照片",
      "group_type": "",
      "source": "manual",
      "created_at": 1779869660
    },
    {
      "id": "<group-id-2>",
      "name": "visual-validate-<group-id-2>",
      "group_type": "AIGC",
      "source": "visual_validate",
      "created_at": 1779870000
    }
  ]
}

字段:

字段	说明
`data`	数组,不是 `groups`
`id`	上游组 ID
`name`	组名
`group_type`	通常 `""`(普通)或 `"AIGC"`(真人认证)
`source`	`"manual"`(用户主动创建)或 `"visual_validate"`(真人认证自动创建)
`created_at`	本地记录时间 Unix 秒

注: 列表里不返回 asset_count 字段。想知道某个组里有多少素材,目前需要客户端自己保留计数。

上传素材

bash

curl -X POST https://www.dianlitoken.com/v1/seedance/assets \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "<upstream-group-id>",
    "url": "https://example.com/my-cat.jpg",
    "name": "橘猫睡觉",
    "asset_type": "Image"
  }'

json

{
  "id": "<upstream-asset-id>",
  "group_id": "<upstream-group-id>",
  "name": "橘猫睡觉",
  "asset_type": "Image"
}

返回只有 id / group_id / name / asset_type,不返回 url / created_at。

字段说明

字段	必填	说明
`group_id`	选填	不传时自动创建一个用户默认组(组名 `default-for-user-<uid>`)
`url`	必填	素材的公网 URL
`name`	选填	显示用的名字
`asset_type`	必填	严格 `"Image"` / `"Video"` / `"Audio"` 之一,大小写敏感

关于 url 字段

平台不替你上传文件, 你需要先把文件传到公网可访问的地方(自己的 OSS / 七牛 / picture-hosting service 等), 然后把 URL 传过来。

真人 / 自有图片做视频必须走素材库

如果想让视频里出现真人 (用户自拍 / 自有照片 / 商品图等), 不要直接把图片公网 URL 写在视频生成请求的 image_url.url 字段里, 而是:

先调 POST /v1/seedance/assets 上传到素材库, 拿到 asset_id
视频生成里用 asset://<asset_id> 引用 (单段 URI)

理由:

素材库做了所有权校验 (asset 必须属于调用方账号), 防止任意用户引用他人上传的人脸
上游官方对 "asset 协议引用" 才会触发完整的人像识别 / 一致性保持能力
直接传公网 URL 可能被上游内容审核拦截 (尤其涉及真人肖像)

在视频生成中引用素材

上传完素材, 在视频生成里用 asset:// 协议引用。

URI 格式

URI 是单段 asset://<asset_id>,不是 asset://<group_id>/<asset_id>。

json

{
  "model": "seedance-2.0-pro",
  "content": [
    {"type": "text", "text": "图中的猫开始跳舞"},
    {
      "type": "image_url",
      "image_url": {"url": "asset://<upstream-asset-id>"},
      "role": "first_frame"
    }
  ]
}

所有权检查

平台会验证:

✅ 素材必须存在
✅ 素材必须属于调用方这个用户

如果你引用别人的素材或不存在的素材, 返回 403:

json

{
  "error": {
    "code": "asset_not_owned",
    "message": "asset \"<asset-id>\" not accessible by caller"
  }
}

查询素材详情

bash

curl https://www.dianlitoken.com/v1/seedance/assets/<asset-id> \
  -H "Authorization: Bearer sk-xxx"

返回是上游官方的原始 JSON(网关只验证所有权后透传),具体字段以上游为准。通常包含上游 URL、类型、时间戳等。

更新素材 URL

bash

curl -X PATCH https://www.dianlitoken.com/v1/seedance/assets/<asset-id> \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/new-photo.jpg"
  }'

仅支持改 url

PATCH 接口只接受 url 字段,不能改名字 / 类型 / group。想改名 / 类型需要删了重传。

请求字段:

字段	必填	说明
`url`	必填	新的素材 URL

返回上游原始 JSON。

删除素材

bash

curl -X DELETE https://www.dianlitoken.com/v1/seedance/assets/<asset-id> \
  -H "Authorization: Bearer sk-xxx"

json

{"deleted": true}

删除后立即生效, 已经在跑的任务不受影响(URL 已传给上游)。
返回只有 {deleted: true},不包含 被删的 id。

支持的素材类型

类型	用途	在 content 里的 type
`Image`	首帧图 / 参考图	`image_url`
`Video`	视频参考 (v2v 模型)	`video_url`
`Audio`	音频参考	`audio_url`

注意类型字符串大小写敏感 — 必须用 Image / Video / Audio(首字母大写),不能用 image / IMAGE。

文件大小 / 格式限制

平台层 未显式限制, 但上游官方通常:

类型	推荐大小	推荐格式
Image	< 10 MB	JPG / PNG / WEBP
Video	< 100 MB	MP4 / MOV (h264 编码)
Audio	< 50 MB	MP3 / WAV / AAC

实际限制以上游官方为准。建议提前压缩 / 转码。

Python 示例 — 完整流程

python

import requests

API_KEY = "sk-xxx"
BASE = "https://www.dianlitoken.com"
H = {"Authorization": f"Bearer {API_KEY}"}

# 1. 创建组
group = requests.post(
    f"{BASE}/v1/seedance/asset-groups",
    headers=H,
    json={"name": "我的素材"},
).json()
group_id = group["id"]
print(f"Group: {group_id}")

# 2. 上传一张参考图(素材必须先在公网托管)
asset = requests.post(
    f"{BASE}/v1/seedance/assets",
    headers=H,
    json={
        "group_id": group_id,
        "url": "https://example.com/my-photo.jpg",
        "name": "我的自拍",
        "asset_type": "Image",
    },
).json()
asset_id = asset["id"]
print(f"Asset: {asset_id}")

# 3. 创建视频任务, 引用素材 — 注意 URI 是单段
task = requests.post(
    f"{BASE}/v1/videos",
    headers=H,
    json={
        "model": "seedance-2.0-pro",
        "content": [
            {"type": "text", "text": "图中人物在沙滩上跑步"},
            {
                "type": "image_url",
                "image_url": {"url": f"asset://{asset_id}"},
                "role": "first_frame",
            },
        ],
        "resolution": "720p",
        "duration": 5,
    },
).json()
print(f"Task: {task['id']}")

常见用例

用例 1: 同一张参考图做 N 个变体

python

# 上传一次
asset_id = upload_asset(image_url="https://my.example.com/photo.jpg")

# 用 5 个不同 prompt 生成 5 个变体
prompts = [
    "图中的人开始跳舞",
    "图中的人在沙滩上跑步",
    "图中的人在雪山徒步",
    "图中的人在城市夜景中走路",
    "图中的人在森林里冥想",
]
for prompt in prompts:
    create_task(prompt, asset_id=asset_id)

用例 2: 真人认证集 → 多视频

详见 06 真人认证。真人认证完成后自动生成一个 asset group(source=visual_validate, group_type=AIGC), 里面是已验证的人脸资产。

下一篇: 06 真人认证 →

05 素材库 (Asset Library) ​

用途 ​

数据模型 ​

Endpoint 总表 ​

创建组 ​

列出我的所有组 ​

上传素材 ​

字段说明 ​

关于 url 字段 ​

真人 / 自有图片做视频必须走素材库 ​

在视频生成中引用素材 ​

所有权检查 ​

查询素材详情 ​

更新素材 URL ​

删除素材 ​

支持的素材类型 ​

文件大小 / 格式限制 ​

Python 示例 — 完整流程 ​

常见用例 ​

用例 1: 同一张参考图做 N 个变体 ​

用例 2: 真人认证集 → 多视频 ​

05 素材库 (Asset Library)

用途

数据模型

Endpoint 总表

创建组

列出我的所有组

上传素材

字段说明

关于 url 字段

真人 / 自有图片做视频必须走素材库

在视频生成中引用素材

所有权检查

查询素材详情

更新素材 URL

删除素材

支持的素材类型

文件大小 / 格式限制

Python 示例 — 完整流程

常见用例

用例 1: 同一张参考图做 N 个变体

用例 2: 真人认证集 → 多视频