火山协议 · 虚拟人像素材管理

如果已有火山方舟素材客户端或希望保留 Action、V4 签名、火山响应信封和 asset:// 引用方式，可以使用 Modelink 的火山素材兼容接口管理 Seedance 私域虚拟人像。

若希望使用 Bearer 鉴权、snake_case 请求体和 qasset:// 引用，请改用 Modelink API · 虚拟人像素材管理。需要真人认证的公众人物或真实形象，请参阅火山协议 · 真人人像素材管理。

流程概览

查询 ProjectName
  → CreateAssetGroup
  → CreateAsset
  → GetAsset 轮询至 Active
  → asset://{AssetId} 引用

CreateAsset 是异步接口。取得素材 ID 后仍需轮询处理状态，只有 Status=Active 的素材才可以用于视频生成。

准备接入点

export MODELINK_API_KEY="替换为你的 Modelink API Key"

# 中国大陆
export MODELINK_BASE_URL="https://api.qnaigc.com"

# 海外使用：
# export MODELINK_BASE_URL="https://api.modelink.ai"

1. 查询可用的 ProjectName

   先调用 GET /v1/asset-projects。项目查询接口使用 Bearer 鉴权：

   curl "$MODELINK_BASE_URL/v1/asset-projects" \
     -H "Authorization: Bearer $MODELINK_API_KEY"

   复制

   响应示例：

   {
     "data": [
       {
         "project_name": "cv1-bogic",
         "supported_asset_types": ["aigc", "liveness_face"]
       }
     ]
   }

   复制

   选择包含 aigc 能力的项目：

   export PROJECT_NAME="cv1-bogic"

   复制

   警告

   后续每个 Action 的 ProjectName 都是必填字段，必须使用该接口返回的 cv1-xxxxx；不支持 default。同一素材组及其素材必须始终使用同一个值。

2. 为每个 Action 生成 V4 签名

   Action 请求固定发送到：

   POST /volcengine/assets/?Action=<Action>&Version=2024-01-01

   复制

   将同一个 Modelink API Key 同时作为 V4 Credential 中的 Access Key 和签名密钥。每个请求都必须携带：

   Authorization: HMAC-SHA256 Credential=...
   X-Date: 20260817T080000Z
   X-Content-Sha256: <最终请求体原始字节的 SHA-256 小写十六进制值>
   Content-Type: application/json

   复制

   下文用 $AUTHORIZATION、$X_DATE 和 $PAYLOAD_HASH 表示针对当前最终 URL 与当前请求体生成的值。

   警告

   签名后不要重新序列化请求体，也不要在不同 Action 之间复用这些变量。X-Date 和 X-Content-Sha256 是参与签名并随请求发送的请求头，不是额外的认证方式。

3. 创建 AIGC 素材组

   使用 CreateAssetGroup 创建虚拟人像素材组：

   {
     "Name": "品牌虚拟人像",
     "Description": "用于品牌宣传视频",
     "GroupType": "AIGC",
     "ProjectName": "cv1-bogic"
   }

   复制

   将上面的 JSON 保存为与签名完全一致的 $BODY 后发送：

   curl "$MODELINK_BASE_URL/volcengine/assets/?Action=CreateAssetGroup&Version=2024-01-01" \
     -H "Authorization: $AUTHORIZATION" \
     -H "X-Date: $X_DATE" \
     -H "X-Content-Sha256: $PAYLOAD_HASH" \
     -H "Content-Type: application/json" \
     -d "$BODY"

   复制

   保存响应 Result.Id：

   export GROUP_ID="group-20260817120000-example"

   复制

4. 向素材组上传素材

   调用 CreateAsset。Name 可选，仅用于 ListAssets 搜索，不会写入视频提示词：

   {
     "AssetType": "Image",
     "GroupId": "group-20260817120000-example",
     "Name": "品牌形象正面照",
     "ProjectName": "cv1-bogic",
     "URL": "https://example.com/avatar.png"
   }

   复制

   curl "$MODELINK_BASE_URL/volcengine/assets/?Action=CreateAsset&Version=2024-01-01" \
     -H "Authorization: $AUTHORIZATION" \
     -H "X-Date: $X_DATE" \
     -H "X-Content-Sha256: $PAYLOAD_HASH" \
     -H "Content-Type: application/json" \
     -d "$BODY"

   复制

   AssetType 支持 Image、Video 和 Audio。URL 必须是公网可访问的 HTTP(S) 地址，不支持 Base64。保存响应中的 Result.Id：

   export ASSET_ID="asset-20260817120500-example"

   复制

5. 轮询素材处理状态

   针对 GetAsset 请求体重新计算签名：

   {
     "Id": "asset-20260817120500-example",
     "ProjectName": "cv1-bogic"
   }

   复制

   curl "$MODELINK_BASE_URL/volcengine/assets/?Action=GetAsset&Version=2024-01-01" \
     -H "Authorization: $AUTHORIZATION" \
     -H "X-Date: $X_DATE" \
     -H "X-Content-Sha256: $PAYLOAD_HASH" \
     -H "Content-Type: application/json" \
     -d "$BODY"

   复制

   Result.Status	含义	处理方式
   Processing	处理中	继续轮询
   Active	已审核可用	可以用于 Seedance 视频生成
   Failed	处理失败	查看错误信息，修正后重新上传

   不要把 CreateAsset 成功响应当作审核完成；必须等待 Status=Active。

6. 在 Seedance 视频任务中引用素材

   将处于 Active 状态的素材 ID 拼接为 asset://{AssetId}。视频任务本身使用 Modelink Bearer 鉴权：

   curl "$MODELINK_BASE_URL/v3/contents/generations/tasks" \
     -H "Authorization: Bearer $MODELINK_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "bytedance/doubao-seedance-2-0-260128",
       "content": [
         {
           "type": "text",
           "text": "图片1在城市街道上自然行走"
         },
         {
           "type": "image_url",
           "image_url": {
             "url": "asset://asset-20260817120500-example"
           },
           "role": "reference_image"
         }
       ],
       "resolution": "720p",
       "ratio": "16:9",
       "duration": 5
     }'

   复制

   素材必须来自当前 API Key 可用的项目，并与视频任务使用的素材/视频渠道关系匹配。完整视频参数见视频 / 火山格式 · Seedance。

查询和管理素材库

所有管理 Action 都必须继续传入资源创建时使用的 ProjectName。

删除不可恢复。删除素材组前应先确认组内素材已经清理；完整请求字段见火山素材兼容接口。

常见问题