Appearance
真人素材库 API
通过 Fhddos 完成字节国内与海外真人认证、LivenessFace 素材管理和 Seedance 视频调用。
真人素材库用于把经过本人授权和活体认证的图片、视频或音频保存为可信素材,再通过 asset://<AssetId> 提交给 Seedance。
这里的“真人认证”是活体检测和同人比对,不是身份证、姓名或公安库实名核验。认证必须由真人本人在返回的 H5 页面完成。
1. 接口与模型
所有素材库请求使用同一个入口:
http
POST /volcark/?Action=<Action>&Version=2024-01-01
Authorization: Bearer <FHDDOS_API_TOKEN>
Content-Type: application/jsonbash
export BASE_URL="https://aiapi.fhddos.com"
export TOKEN="oh-xxxxxxxxxxxxxxxx"请求体中的 model 用于 Fhddos 选择国内或海外渠道,不会下发给字节控制面上游。建议在整条认证和素材流程中始终使用同一个模型和同一个 ProjectName。
| 区域 | 推荐模型 | 说明 |
|---|---|---|
| 国内火山方舟 | doubao-seedance-2-0、doubao-seedance-2-0-fast、doubao-seedance-2-0-mini、doubao-seedance-2-5 | 使用国内官方真人素材渠道 |
| 海外 BytePlus | dreamina-seedance-2-0、dreamina-seedance-2-0-fast、dreamina-seedance-2-0-mini、dreamina-seedance-2-5 | 使用海外官方真人素材渠道 |
真人素材不会在国内、海外渠道之间自动迁移或降级。已经创建真人 Group / Asset 后,请继续使用原模型地域和 Project。
2. 完整流程
- 调用
CreateVisualValidateSession创建一次性认证会话。 - 保存响应中的
BytedToken,让真人本人打开H5Link完成活体认证。 - H5 跳转到
CallbackURL后,服务端调用GetVisualValidateResult。 - 从成功结果取得
GroupId。该组类型固定为LivenessFace。 - 使用
CreateAsset向该 Group 添加图片、视频或音频。 - 用
GetAsset轮询,直到素材变为Active或Failed。 - 只有
Active素材可以通过asset://<AssetId>用于 Seedance。
H5 回调只能作为流程通知。即使回调参数里带有 resultCode=10000,服务端仍应调用 GetVisualValidateResult 获取可信 GroupId。
3. 创建真人认证会话
bash
curl -X POST "$BASE_URL/volcark/?Action=CreateVisualValidateSession&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"CallbackURL": "https://your-domain.example/real-person/callback",
"ProjectName": "default"
}'典型响应:
json
{
"ResponseMetadata": {
"RequestId": "0217...",
"Action": "CreateVisualValidateSession",
"Version": "2024-01-01",
"Service": "ark"
},
"Result": {
"BytedToken": "one-time-token",
"H5Link": "https://example.byte-provider.com/verify/...",
"CallbackURL": "https://your-domain.example/real-person/callback"
}
}| 字段 | 说明 |
|---|---|
CallbackURL | 必填,必须是公网 HTTPS URL |
ProjectName | 可选,默认 default;后续请求必须保持一致 |
BytedToken | 一次性认证凭证;不要写入日志或业务数据库 |
H5Link | 一次性真人认证地址,只交给本次获得授权的真人本人 |
ExpiresIn | Token 剩余有效期(秒);以响应值为准,超时后需要重新创建认证会话 |
CallbackURL 只用于 H5 结束后的跳转提示,页面本身不影响认证结果,可以是自有回调页,也可以先指向一个返回 200 的静态页;认证是否成功始终以 GetVisualValidateResult 的返回为准。
如需指定 H5 语言,可在 H5Link 后追加 lng=zh、lng=en 或 lng=zh-Hant。
4. 查询认证结果
真人本人完成 H5 后,用原 BytedToken 查询:
bash
curl -X POST "$BASE_URL/volcark/?Action=GetVisualValidateResult&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"BytedToken": "one-time-token",
"ProjectName": "default"
}'成功结果:
json
{
"ResponseMetadata": {
"RequestId": "0217...",
"Action": "GetVisualValidateResult",
"Version": "2024-01-01",
"Service": "ark"
},
"Result": {
"GroupId": "group-real-person-example"
}
}GroupId 已由 Fhddos 绑定到当前 API 用户、地域和 Project。真人 Group 不能通过 CreateAssetGroup 创建,也不能作为其他用户或其他地域的素材组使用。
5. 创建真人素材
bash
curl -X POST "$BASE_URL/volcark/?Action=CreateAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"GroupId": "group-real-person-example",
"URL": "https://media.example.com/authorized-person.jpg",
"AssetType": "Image",
"Name": "main-portrait",
"ProjectName": "default"
}'成功响应只返回素材 ID:
json
{
"ResponseMetadata": {
"RequestId": "0217...",
"Action": "CreateAsset",
"Version": "2024-01-01",
"Service": "ark"
},
"Result": {
"Id": "asset-real-person-example"
}
}| 字段 | 必填 | 说明 |
|---|---|---|
GroupId | 是 | 真人认证结果返回的 Group ID |
URL | 是 | 上游可下载的公网 URL;不支持 Base64 |
AssetType | 是 | Image、Video 或 Audio |
Name | 否 | 管理名称,最长 64 字符 |
ProjectName | 否 | 默认 default,必须与 Group 一致 |
每个真人 Group 只能对应一位真人。包含多人、与认证本人不同或无法完成同人比对的素材会进入 Failed。
常用媒体边界:
| 类型 | 格式 | 大小与时长 |
|---|---|---|
| 图片 | jpeg、png、webp、bmp、tiff、gif、heic/heif | 小于 30 MB,宽高 300–6000 px |
| 视频 | mp4、mov | 2–15 秒,不超过 200 MB,24–60 FPS |
| 音频 | wav、mp3 | 2–15 秒,不超过 15 MB |
Moderation.Strategy=Skip 不开放。
6. 查询素材状态
CreateAsset 是异步操作。使用官方字段 Id 查询,直到进入终态:
bash
curl -X POST "$BASE_URL/volcark/?Action=GetAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"Id": "asset-real-person-example",
"ProjectName": "default"
}'json
{
"ResponseMetadata": {
"RequestId": "0217...",
"Action": "GetAsset",
"Version": "2024-01-01",
"Service": "ark"
},
"Result": {
"Id": "asset-real-person-example",
"GroupId": "group-real-person-example",
"AssetType": "Image",
"Status": "Active",
"Name": "main-portrait",
"ProjectName": "default"
}
}Status | 是否可用于推理 | 建议处理 |
|---|---|---|
Processing | 否 | 有界轮询 GetAsset |
Active | 是 | 使用 asset://<Id> |
Failed | 否 | 停止轮询,按错误原因修正素材后重新创建 |
查询响应中的素材 URL 是短期地址,不要保存或用于 Seedance 请求。
7. 列表、更新和删除
支持以下 Action:
| Action | 关键字段 | 说明 |
|---|---|---|
ListAssetGroups | Filter.GroupType=LivenessFace、分页、ProjectName | 只返回当前用户绑定的真人 Group |
ListAssets | Filter.GroupType=LivenessFace、GroupIds、Statuses、分页 | 只返回当前用户绑定的真人素材 |
GetAssetGroup | Id、ProjectName | 查询真人 Group |
UpdateAsset | Id、Name、ProjectName | 修改素材名称 |
UpdateAssetGroup | Id、Name、Description、ProjectName | 修改 Group 名称和描述 |
DeleteAsset | Id、ProjectName | 删除素材,不可恢复 |
DeleteAssetGroup | Id、ProjectName | 删除 Group 及组内素材,不可恢复 |
列表示例:
bash
curl -X POST "$BASE_URL/volcark/?Action=ListAssets&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"ProjectName": "default",
"PageNumber": 1,
"PageSize": 20,
"Filter": {
"GroupType": "LivenessFace",
"GroupIds": ["group-real-person-example"],
"Statuses": ["Active"]
}
}'ListAssets 会把 Statuses 规范化为供应商要求的 PROCESSING、ACTIVE、FAILED;调用方可继续使用上例的官方字段写法。
删除示例:
bash
curl -X POST "$BASE_URL/volcark/?Action=DeleteAsset&Version=2024-01-01" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"Id": "asset-real-person-example",
"ProjectName": "default"
}'删除请求开始后,该素材会立即停止接受新的 asset:// 推理。上游删除失败时,可以使用同一个官方 Id 重试。Delete 只接受字段 Id,不接受 ID、AssetId、AssetID 或 asset_id。
Update* 与 Delete* 的开放状态以当前账号为准。如果返回 403 InvalidAction,说明该 Action 尚未在当前账号开放,可提交工单确认。
8. 使用真人素材生成视频
只有 Active 素材可以用于视频。原生 Seedance 任务示例:
bash
curl -X POST "$BASE_URL/volcark/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-5",
"content": [
{
"type": "text",
"text": "以 Image 1 中的人物为主角,生成一段自然光下的电影感短片。"
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-real-person-example"
}
}
],
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"generate_audio": true
}'海外调用把模型换成对应的 dreamina-*,并继续使用海外认证流程创建的 Asset。不要在国内、海外 Asset 之间混用 ID。
OpenAI 风格 /v1/videos 也接受 asset:// 参考素材:
json
{
"model": "doubao-seedance-2-5",
"prompt": "保持参考人物身份和主要外观,生成自然走动镜头。",
"input_reference": ["asset://asset-real-person-example"],
"seconds": 5,
"resolution": "720p",
"ratio": "16:9"
}9. 错误响应
错误保持字节 ResponseMetadata.Error 结构:
json
{
"ResponseMetadata": {
"RequestId": "0217...",
"Action": "GetAsset",
"Version": "2024-01-01",
"Service": "ark",
"Error": {
"Code": "ResourceNotFound.Asset",
"Message": "asset not found"
}
}
}常见处理:
| 错误 | 含义 |
|---|---|
InvalidParameter.Version | 真人接口必须使用 Version=2024-01-01 |
MissingParameter.Id | Get / Update / Delete 缺少官方字段 Id |
asset_not_found / ResourceNotFound.Asset | 素材不存在或不属于当前用户绑定 |
asset_not_active | 素材尚未 Active、已经失败或已撤回 |
asset_region_mismatch | 素材与请求模型地域不一致 |
| 权限或配额类错误 | 当前账号没有可用的对应地域真人素材能力,请提交工单确认开通状态 |
真人素材上游错误会使用中性错误信息,避免把一次性凭证或临时媒体 URL 回显到响应和日志。
10. 计费与合规
- 真人认证会话与素材管理接口(Create / Get / List / Update / Delete)本身不产生视频计费项;只有使用
asset://提交并成功完成的 Seedance 生成任务才按视频计费,价格与普通 Seedance 任务一致。 - 上游目前把真人认证标注为限时免费,后续价格和结束时间未公布;请勿把该状态视为长期免费承诺。
- 调用方必须在认证前取得真人本人明确、主动且可撤回的单独同意,并提供删除和撤回入口。
- 不要在日志、工单、客服记录或数据库中保存人脸内容、完整
H5Link、BytedToken、AK/SK、Authorization 或临时素材 URL。 - 真人 H5、Group 和 Asset 的可用性取决于对应国内或海外官方渠道权益;如接口返回权限或配额错误,请提交工单确认开通状态。
模型参数和视频计费详情见 Seedance 2.5、Doubao Seedance 2.0 和 BytePlus Dreamina Seedance 2.0。