RealFace

什么是 Real Face

Token360 RealFace 集成了 BytePlus ModelArk 真人资产库。上传到已完成验证的 Real Face 分组中的图像，可在视频生成任务中作为角色参考，以生成一致的角色外观。

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

支持的模型

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

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

设置 Real Face 资产

在 Assets 页面设置 Real Face 资产

在 Playground 中使用 RealFace 之前，请先在 Assets 页面创建 Real Face 资产组，完成真人验证，并将图像上传到该分组。

1. 打开 Assets

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

2. 创建 Real Face 分组

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

创建后，弹窗会显示验证链接和二维码。请仅发送给被验证人本人。链接有效期为 2 分钟（120 秒）。如果链接过期且未完成验证，请重新打开分组详情获取新链接。进行验证、上传或使用真人图像前，请先取得被验证人的必要授权；不要公开、转发或记录验证链接及二维码。

该分组会显示在 Asset groups 表格中。请通过 Status 列确认分组已激活后，再向其中上传图像。

3. 上传资产

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

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

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

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

通过 API 设置 Real Face 资产

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

1. 创建 Real Face 分组

调用 POST /v1/asset-groups 并设置 groupKind=REAL_FACE 创建 RealFace 分组。响应会返回公开 assetGroupId，并可能包含 h5Link 真人验证链接。

Shell

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": "Real Face Group",
6    "groupKind": "REAL_FACE"
7  }'

请仅将 h5Link 发送给被验证人本人。链接有效期为 2 分钟（120 秒）。如果链接过期且未完成验证，请调用 GET /v1/asset-groups/{assetGroupId} 获取新链接。进行验证、上传或使用真人图像前，请先取得被验证人的必要授权；不要公开、转发或记录验证链接。

2. 获取已验证的资产组 ID

验证完成后，把创建响应中的 assetGroupId 作为上传接口的 groupId。也可以调用带有 groupKind=REAL_FACE 的 GET /v1/asset-groups 查找 active 的 RealFace 分组。

Shell

1curl "https://api.token360.ai/v1/asset-groups?groupKind=REAL_FACE&status=active&current=1&size=100" \
2  -H "Authorization: Bearer sk-your-api-key"

3. 上传 RealFace 资产

使用 POST /v1/assets 通过 multipart form data 上传图像文件。groupId 请填写 active Real Face 分组的 assetGroupId。

Shell

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

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

4. 轮询直到资产变为 active

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

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

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

使用 Real Face

在 Playground 中使用 RealFace

1. 选择支持的模型

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

2. 选择视频模式

RealFace 可在以下视频模式中使用：

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

3. 选择 RealFace 资产

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

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

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

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

4. 生成视频

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

通过 API 使用 RealFace

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

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

调用视频生成 API 的 First-frame I2V 场景时，请使用该场景模型参数 schema 中的媒体输入字段。将 RealFace 资产 URL 放在 first_frame 条目的 frame_images[].image_url.url 中。

Shell

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 verified person 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_first_frame_asset_id" }
12      }
13    ],
14    "duration": 5,
15    "resolution": "720p",
16    "generate_audio": false
17  }'

资产引用格式


`frame_images[].type`	`image_url`
`frame_images[].frame_type`	`first_frame`
`frame_images[].image_url.url`	`asset://{assetId}`

多个资产

First-frame I2V 使用一个首帧资产。如需添加更多 RealFace 资产作为身份参考，请使用 Reference images 或 Multimodal reference 场景。

限制

RealFace 资产仅适用于参数 schema 支持 RealFace 输入的视频模型
每个资产必须属于 active 的 Real Face 分组，且资产本身处于 active 状态
资产的可用性取决于 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} 格式传入。