素材管理 API

📌 使用 Seedance 2.0 视频生成模型时，如果需要使用虚拟真人进行视频生成，需要上传生成方自有版权真人作为素材库素材，在生成时引用。您需确保上传的虚拟人像符合以下条件：

您合法拥有该素材，并享有完整的使用及处分权限。素材不包含未获授权的第三方商标、标识类内容。
素材不得与任何自然人肖像或形象雷同，素材不存在抄袭、盗用情形，不会侵害任何第三方的人格权、知识产权等合法权益。
素材不包含违反法规、违背公序良俗、危害国家安全的内容。

基础信息

基础路径：/api/business/v1

认证方式：Authorization: Bearer sk_live_...

示例环境变量：

export HUB_BASE_URL='https://silvamux.tingyutech.com'
export HUB_TOKEN='sk_live_xxx'

数据模型

AssetView

素材对象示例：

{
  "id": "AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y",
  "url": "https://example.com/image.png",
  "asset_type": "Image",
  "name": "cover-image",
  "asset_url": "asset://asset-123456",
  "status": "processing",
  "created_at": "2026-03-27T10:00:00Z"
}

字段说明：

id：素材 ID
url：原始素材 URL
asset_type：素材类型
name：素材名称
asset_url：素材引用地址，格式为 asset://xxxxxxxxx
status：素材状态，可能值为 processing、active、failed ；注意只有素材为 active 的时候才可以推理使用
created_at：创建时间，RFC 3339 格式

创建素材

POST /api/business/v1/assets

用于把一个可公开访问的 URL 注册到素材库中。

请求体

{
  "url": "https://example.com/image.png",
  "asset_type": "Image",
  "name": "cover-image"
}

字段说明：

url：必填，素材的公开 URL
asset_type：必填，素材类型。可选： Image, Video, Audio
name：必填，素材名字，12 字符以内。

成功响应

成功时返回 201 Created，响应体是一个 AssetView：

{
  "id": "AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y",
  "url": "https://example.com/image.png",
  "asset_type": "Image",
  "name": "cover-image",
  "asset_url": "asset://asset-123456",
  "status": "processing",
  "created_at": "2026-03-27T10:00:00Z"
}

新建完成后，素材通常会先处于 processing 状态；后续再变成 active 或 failed。素材只有在 active 时才可被推理使用。

curl 示例

使用 API Key

curl -X POST "$HUB_BASE_URL/api/business/v1/assets" \
  -H "Authorization: Bearer $HUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/image.png",
    "asset_type": "Image",
    "name": "cover-image"
  }'

列出素材

GET /api/business/v1/assets

列出当前组织下的素材。

查询参数

limit：每页数量，范围 1-100，默认 20
cursor：分页游标，用于获取下一页

成功响应

成功时返回 200 OK：

{
  "items": [
    {
      "id": "AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y",
      "url": "https://example.com/image.png",
      "asset_type": "Image",
      "name": "cover-image",
      "asset_url": "asset://asset-123456",
      "status": "active",
      "created_at": "2026-03-27T10:00:00Z"
    }
  ],
  "next_cursor": "eyJ0aW1lIjoiMjAyNi0wMy0yN1QxMDowMDowMFoifQ==",
  "has_more": true
}

字段说明：

items：当前页素材列表
next_cursor：下一页游标；如果没有更多数据，通常为 null
has_more：是否还有下一页

curl 示例

获取第一页

curl "$HUB_BASE_URL/api/business/v1/assets?limit=20" \
  -H "Authorization: Bearer $HUB_TOKEN"

获取下一页

拿到上一页返回的 next_cursor 后，继续请求：

curl "$HUB_BASE_URL/api/business/v1/assets?limit=20&cursor=eyJ0aW1lIjoiMjAyNi0wMy0yN1QxMDowMDowMFoifQ==" \
  -H "Authorization: Bearer $HUB_TOKEN"

配合 `jq` 查看返回结果

curl -s "$HUB_BASE_URL/api/business/v1/assets?limit=20" \
  -H "Authorization: Bearer $HUB_TOKEN" | jq

只看素材 ID、名称和状态：

curl -s "$HUB_BASE_URL/api/business/v1/assets?limit=20" \
  -H "Authorization: Bearer $HUB_TOKEN" | jq '.items[] | {id, name, status, asset_url}'

获取单个素材

GET /api/business/v1/assets/{asset_id}

根据素材 ID 获取单个素材的详细信息。

路径参数

asset_id：必填，素材 ID

成功响应

成功时返回 200 OK，响应体是一个 AssetView：

{
  "id": "AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y",
  "url": "https://example.com/image.png",
  "asset_type": "Image",
  "name": "cover-image",
  "asset_url": "asset://asset-123456",
  "status": "active",
  "created_at": "2026-03-27T10:00:00Z"
}

curl 示例

curl "$HUB_BASE_URL/api/business/v1/assets/AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y" \
  -H "Authorization: Bearer $HUB_TOKEN"

可以用来轮询素材状态，直到 status 变为 active。

错误响应

错误响应 HTTP 状态码 >= 400，使用 application/problem+json，字段包括：

status：HTTP 状态码
title：错误标题
detail：错误详情
errors：更细粒度的字段校验错误列表

常见问题：

401 Unauthorized：Authorization 无效、过期
400 Bad Request：请求体字段缺失、类型错误，或者分页参数非法

最小调用流程

准备一个外网可访问的图片 URL
调用 POST /api/business/v1/assets 创建素材
从响应里拿到 id、asset_url
调用 GET /api/business/v1/assets 确认素材已经出现在列表中
如果 status 还是 processing，轮询列表接口，直到变成 active

在生成视频时引用素材

使用 API 返回的 asset_url 作为 image_url 或者 video_url ，正常调用接口即可：

import os
import time
# Install SDK:  pip install 'volcengine-python-sdk[ark]'
from volcenginesdkarkruntime import Ark

client = Ark(
    base_url='https://silvamux.tingyutech.com/api/v3',
    api_key=os.environ.get("SILVAMUX_API_KEY"),
)

if __name__ == "__main__":
    print("----- create request -----")
    create_result = client.content_generation.tasks.create(
        model="goldsaucer/advanced-video-generation-2-0",
        content=[
            {
                "type": "text",
                "text": "图片1中美妆博主用中文进行介绍，妆容改为明艳大气，去掉脸部反光，笑容甜美，近景镜头，手持图片2的面霜面向镜头展示，清新简约背景，元气甜美风格。博主台词：挖到本命面霜了！质地像云朵一样软糯，一抹就吸收，熬夜急救、补水保湿全搞定，素颜都自带柔光感。"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "asset://asset-20260224200602-qn7wr" # Asset ID
                },
                "role": "reference_image"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_edit_pic1.jpg"
                },
                "role": "reference_image"
            },
        ],
        generate_audio=True,
        ratio="16:9",
        duration=11,
        watermark=True,
    )
    print(create_result)
    print("----- polling task status -----")
    task_id = create_result.id
    while True:
        get_result = client.content_generation.tasks.get(task_id=task_id)
        status = get_result.status
        if status == "succeeded":
            print("----- task succeeded -----")
            print(get_result)
            break
        elif status == "failed":
            print("----- task failed -----")
            print(f"Error: {get_result.error}")
            break
        else:
            print(f"Current status: {status}, Retrying after 30 seconds...")
            time.sleep(30)

API 参考

请查看业务 API

最佳实践——私域素材资产上传案例

⚠️ 在上传素材资产时，若将目标人脸图、全身参考图及细节参考图合并为同一张图片，可能导致各参考元素在画面中占比较小，从而增加模型识别难度，造成生成视频中的人物形象与所上传素材资产出现偏差，或造成生成视频中素人脸被误识别为明星脸而触发风控拦截。

建议在上传素材资产时，将人物面部特写、服装细节等关键内容独立分割为单独的图片进行上传。具体可参考如下规则及示例：

示例 1

案例 A

输入内容

给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词

背景参考图片 1，月白虚影闪过，公子 （妆造参考图片 2；人物形象严格参考图片 3） 旋身开合折扇，鎏金扇刃弹出，墨竹扇面翻飞，慢鼓重响 1 声；特写：折扇刃格挡反派长刀，扇骨与刀身相击，公子唇角勾轻佻笑意，眼神却冷冽，指腹轻转扇柄。；慢镜：公子侧身贴地滑步，折扇刃贴反派腿侧划过，带起一道浅痕，锦袍下摆扫过地面，玉簪轻晃。快切：公子旋身抬手，折扇刃飞射而出，擦过反派脖颈，钉入身后木柱，反派僵立不敢动。反转：身后突然传来掌风，公子旋身接掌，指尖相触时借力后跳，折扇刃从木柱飞回手中，眼神警惕。慢镜高光：公子折扇半开，扇刃抵唇侧，抬眸望向身后，碎发被风吹起，眉梢微扬，带一丝桀骜。拉镜：公子立于庭院石台上，折扇轻摇，镜头拉远，庭院四角同时浮现戴面具的黑影（持弯刀，呈合围之势）。定格：公子折扇合起一半，扇刃露鎏金锋芒，抬步向前，画面压暗，只留他的侧影和扇刃光，音效骤停。音效：折扇开合脆响 + 刃风切割声 + 慢鼓卡点（偏沉稳）。

输出内容

案例 B

输入内容

给出背景参考图、人物妆造三视图、提示词（缺少人物面部无表情特写图）

背景参考图片 1，月白虚影闪过，公子 （参考图片 2） 旋身开合折扇，鎏金扇刃弹出，墨竹扇面翻飞，慢鼓重响 1 声；特写：折扇刃格挡反派长刀，扇骨与刀身相击，公子唇角勾轻佻笑意，眼神却冷冽，指腹轻转扇柄。；慢镜：公子侧身贴地滑步，折扇刃贴反派腿侧划过，带起一道浅痕，锦袍下摆扫过地面，玉簪轻晃。快切：公子旋身抬手，折扇刃飞射而出，擦过反派脖颈，钉入身后木柱，反派僵立不敢动。反转：身后突然传来掌风，公子旋身接掌，指尖相触时借力后跳，折扇刃从木柱飞回手中，眼神警惕。慢镜高光：公子折扇半开，扇刃抵唇侧，抬眸望向身后，碎发被风吹起，眉梢微扬，带一丝桀骜。拉镜：公子立于庭院石台上，折扇轻摇，镜头拉远，庭院四角同时浮现戴面具的黑影（持弯刀，呈合围之势）。定格：公子折扇合起一半，扇刃露鎏金锋芒，抬步向前，画面压暗，只留他的侧影和扇刃光，音效骤停。音效：折扇开合脆响 + 刃风切割声 + 慢鼓卡点（偏沉稳）。

输出内容

案例分析

同样是古风打斗剧情，案例 A 的输出视频更加还原人物面部特征；案例 B 的人物面部特征一致性遵循不佳。

示例 2

案例 A

输入内容

给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词

3d 动画风格，背景参考图片 1。人物 A（妆造参考图片 2；面部特征严格参考图片 3）和人物 B（妆造参考图片 4；面部特征严格参考图片 5）手牵手走在花园的小径上，镜头处于人物背后。镜头切到前面，人物 A 拿起一朵鲜花，轻轻递给人物 B。背景音效：轻柔的风吹动树叶和花朵，鸟鸣声。人物 B 微笑接过花，轻轻闻了闻花香，然后蹲下低头与人物 A 微笑对视，轻轻拍拍人物 A 的头，说：“thank you”。背景音效：风铃轻响。

输出内容

案例 B

输入内容

给出背景参考图、人物妆造三视图、提示词

3d 动画风格，背景参考图片 1。人物 A（参考图片 2）和人物 B（参考图片 3）手牵手走在花园的小径上，镜头处于人物背后。镜头切到前面，人物 A 拿起一朵鲜花，轻轻递给人物 B。背景音效：轻柔的风吹动树叶和花朵，鸟鸣声。人物 B 微笑接过花，轻轻闻了闻花香，然后蹲下低头与人物 A 微笑对视，轻轻拍拍人物 A 的头，说：“thank you”。背景音效：风铃轻响。

输出内容

示例 2

案例 A

输入内容

给出背景参考图、人物妆造三视图、人物面部无表情特写图、提示词

输出内容

案例 C

输入内容

给出背景参考图、人物妆造正视图、提示词

输出内容

案例分析

同样是温馨亲子剧情：

案例 A 输入内容包括：背景参考图、人物妆造三视图、人物面部无表情特写图、提示词；案例 B 输入内容包括：背景参考图、人物妆造三视图、提示词；案例 C 输入内容包括：背景参考图、人物妆造正面图、提示词。

案例 A 的输出视频更加还原人物面部特征；案例 B 的输出视频人物面部特征一致性遵循不佳；案例 C 人物妆造、面部特征一致性遵循不佳。

素材管理 API

基础信息

数据模型

AssetView

创建素材

请求体

成功响应

curl 示例

使用 API Key

列出素材

查询参数

成功响应

curl 示例

获取第一页

获取下一页

配合 jq 查看返回结果

获取单个素材

路径参数

成功响应

curl 示例

错误响应

最小调用流程

在生成视频时引用素材

API 参考

最佳实践——私域素材资产上传案例

示例 1

案例 A

输入内容

输出内容

案例 B

输入内容

输出内容

案例分析

示例 2

案例 A

输入内容

输出内容

案例 B

输入内容

输出内容

示例 2

案例 A

输入内容

输出内容

案例 C

输入内容

输出内容

案例分析

联系销售

配合 `jq` 查看返回结果