Virtual Portrait

什么是 Virtual Portrait

Token360 Virtual Portrait 集成了 BytePlus ModelArk AIGC 资产库，可将 AI 生成的角色图像作为视频生成工作流中的参考资产使用，无需真人验证。

每个资产通过 Token360 资产 ID 标识，格式为 ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。

与 RealFace 的主要区别

支持的模型

Virtual Portrait 资产仅适用于兼容的视频模型。使用 asset:// 输入前，请调用 GET /v1/models/{model_id}，并在 parameter_schema 中确认所需媒体字段和参数可选值。

下方 API 示例使用 seedance-2.0 展示 BytePlus 视频模型的请求结构。使用其他模型时，请以该模型 schema 中暴露的字段名和参数值为准。

设置 Virtual Portrait 资产

在 Assets 页面设置 Virtual Portrait 资产

在 Playground 中使用 Virtual Portrait 之前，请先在 Assets 页面创建 Virtual Portrait 资产组，并将图像上传到该分组。

1. 打开 Assets

点击右上角头像，在下拉菜单中选择 Assets。

2. 创建 Virtual Portrait 分组

在 Asset groups 区域点击 New group。在 Create asset group 弹窗中选择 Virtual Portrait，输入 Group name，然后点击 Create。Virtual Portrait 分组中的上传不使用单文件过期时间；弹窗会选中 No fixed expiry，且该选项不可修改。

该分组会显示在 Asset groups 表格中，创建后即可使用，无需 H5 真人验证步骤。

3. 上传资产

在 Assets 区域中点击 Upload 并选择图像文件。在 Upload file 弹窗中填写 Display name，将 Asset group 设置为 Virtual Portrait 分组，然后点击 Upload。Virtual Portrait 分组的 Retention 选择器会被锁定，因为这类上传不使用单文件过期时间。

• 资产会显示在所选分组下的 Assets 表格中
• 每个资产都有唯一 Asset ID，格式为 ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• 点击 Asset ID 可复制，用于 API 调用
• 资产可能会先显示为 Processing，状态变为 Active 后才能使用

如需只查看某个 Virtual Portrait 分组的资产，请使用 Assets 表格中的 Asset group 筛选器。该筛选器只改变表格显示内容；上传目标需要在 Upload file 弹窗中选择。

只有 Virtual Portrait 分组中状态为 已激活 的资产才能用于 Virtual Portrait。普通资产不能直接用于该场景。

通过 API 设置 Virtual Portrait 资产

如需在 UI 之外创建和准备 Virtual Portrait 资产，请使用 Assets API。

1. 创建 Virtual Portrait 分组

调用 POST /v1/asset-groups 并设置 groupKind=VIRTUAL_PORTRAIT 创建 Virtual Portrait 分组。响应会返回公开 assetGroupId，并且分组会立即处于 active 状态。

1curl -X POST https://api.token360.ai/v1/asset-groups \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Virtual Portrait Name",
6    "groupKind": "VIRTUAL_PORTRAIT"
7  }'

2. 上传 Virtual Portrait 资产

使用 POST /v1/assets 通过 multipart form data 上传图像文件。把 Virtual Portrait 分组的 assetGroupId 作为 groupId。

1curl -X POST https://api.token360.ai/v1/assets \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -F "groupId=your-virtual-portrait-group-id" \
4  -F "file=@your-image-file.jpg" \
5  -F "name=Asset Name"

上传响应会返回以 ta_ 开头的公开 assetId。在 Virtual Portrait 视频输入中，请按 asset://{assetId} 格式使用。

3. 轮询直到资产变为 active

请轮询 GET /v1/assets/{assetId} 或 GET /v1/assets?groupId=your-virtual-portrait-group-id，直到资产状态变为 active。

资产变为 active 后，请使用公开 assetId，并按 asset://{assetId} 格式传入。

不要使用普通用户上传资产 ID（例如 ua_ 前缀的 ID）作为 Virtual Portrait 引用。如果图片是作为普通资产上传的，请重新上传到已激活的 Virtual Portrait 分组。

使用 Virtual Portrait

在 Playground 中使用 Virtual Portrait

1. 选择支持的模型

在 Playground 中，选择参数 schema 支持 Virtual Portrait 图片输入的视频模型。

2. 选择视频模式

Virtual Portrait 资产可在以下视频模式中使用：

• First-frame I2V
• First & last frame
• Reference images
• Multimodal reference
• Edit video
• Extend video

3. 选择资产

对于支持的视频模式，每个兼容的媒体区块（例如 First frame、Last frame 或 Reference images）标题栏中都有来源按钮：

• 点击上传图标，从本机添加文件
• 点击资源库图标（提示文字为 From assets），打开 Choose from your library

在 Choose from your library 中，将类型下拉框设置为 Virtual Portrait，或按资产名称、资产 ID 搜索。图像槽位会锁定为只显示图片，也可以按分组筛选。选择器只允许选择 active 且未过期的资产。

对于首帧、尾帧等单图槽位，点击资产卡片后会立即使用该资产。对于参考图等多图槽位，先选择一个或多个资产卡片，再点击 Use selected。在 Playground 中，已选择的 Virtual Portrait 输入会显示 资产 标记。

4. 生成视频

选择 Virtual Portrait 资产后，填写提示词和其他参数，然后点击 生成。

通过 API 使用 Virtual Portrait

您可以在 Assets 页面找到资产 ID。按 Virtual Portrait 分组筛选，然后点击 Asset ID 即可复制。

使用公开 assetId，并按 asset://{assetId} 格式引用 Virtual Portrait 资产，例如 asset://ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。

请使用各视频模型输入参数 schema 中显示的媒体输入字段：

• 首帧或尾帧：使用 frame_images[].image_url.url
• 参考图和其他图像参考：使用 input_references[].image_url.url

1curl -X POST https://api.token360.ai/v1/videos \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "seedance-2.0",
6    "prompt": "A stylized virtual character smiles and turns toward the camera in soft studio light",
7    "frame_images": [
8      {
9        "type": "image_url",
10        "frame_type": "first_frame",
11        "image_url": { "url": "asset://ta_virtual_portrait_asset_id" }
12      }
13    ],
14    "duration": 6,
15    "resolution": "720p",
16    "generate_audio": false
17  }'

限制

• Virtual Portrait 资产仅适用于参数 schema 支持 Virtual Portrait 输入的视频模型
• 每个资产必须属于已激活的 Virtual Portrait Group，且资产本身也必须为已激活状态
• 资产可用性受 BytePlus ModelArk 服务状态影响

配额、使用保护与删除

Virtual Portrait 与 Real Face 资产共享当前个人或租户作用域的托管资产配额。个人作用域默认额度为 50,000，租户作用域默认额度为 500,000。批量上传前及自动化监控中，建议调用 GET /v1/assets/quota 查询实时额度。

上传后，请轮询资产直至 status 为 active，再在视频生成请求中使用 asset://ta_...。视频任务进行期间会保护其引用的托管资产。删除受保护资产会返回 ASSET_DELETE_USAGE_ACTIVE，应在视频任务进入终态后重试。

• 单资产：调用 DELETE /v1/assets/{assetId}；如果返回操作 ID，再轮询 GET /v1/assets/operations/{operationId}。
• 指定资产批删：创建 selectionType=ASSET_IDS 的删除任务，一次传入 1–20 个公开资产 ID。
• 符合条件的托管资产批删：先预览 ALL_OWNED_BY_ME 或 ALL_IN_CURRENT_SCOPE，再提交预览返回的确认 token。
• 批删接口同时支持 JWT 登录会话和 sk-* API Key。

使用资产时，请仅使用 Token360 返回的公开 assetId，并按 asset://{assetId} 格式传入。