Seedance 真人人像素材

与虚拟人像不同,真人人像必须先完成真人认证(由被拍摄者本人在移动端 H5 完成活体认证并授权),认证通过后才能获得可提交素材的素材组。接口同样采用火山方舟原生 Action 协议(POST /?Action=...&Version=2024-01-01,JSON 请求体,PascalCase 字段),鉴权只需 MaiToken API Key。

完整流程:

• 创建真人认证会话,获取认证凭证(BytedToken)与 H5 认证链接
• 被拍摄者本人打开 H5 完成活体认证
• 查询认证结果,获得素材组 Id(该组从此归属你的账号)
• 向该组提交真人素材,轮询状态后在生成中使用

Authorizations

Authorization: Bearer YOUR_API_KEY

接入流程

sequenceDiagram    participant Client as 调用方    participant MaiToken as MaiToken    participant User as 被拍摄者     Client->>MaiToken: 1. CreateVisualValidateSession    MaiToken-->>Client: Result.BytedToken + H5 认证链接     User->>User: 2. 打开 H5 完成活体认证并授权     Client->>MaiToken: 3. GetVisualValidateResult (BytedToken)    MaiToken-->>Client: Result.GroupId (真人素材组)     Client->>MaiToken: 4. CreateAsset (GroupId + 素材 URL)    MaiToken-->>Client: Result.Id (asset-*)     loop 直到素材可用      Client->>MaiToken: 5. GetAsset (Id)      MaiToken-->>Client: Result.Status    end

第一步:创建真人认证会话

调用 CreateVisualValidateSession 发起认证。响应的 Result 中包含 BytedToken(后续查询认证结果的凭证,30 分钟内有效)与供被拍摄者打开的 H5 认证链接。

请求体字段:

• CallbackURL(可选):认证完成后的回调地址,回调参数中 resultCode=10000 表示认证成功

第二步:被拍摄者完成 H5 认证

将 H5 链接发给被拍摄者本人,在移动端完成活体认证与肖像授权。如配置了 CallbackURL,认证完成后回调参数中 resultCode=10000 表示成功。

第三步:查询认证结果,认领素材组

认证完成后,用 BytedToken 调用 GetVisualValidateResult。成功时返回该认证生成的真人素材组 Id——此调用同时把素材组认领到你的账号名下,之后才能对它执行素材操作。

注意:BytedToken 必须是你自己创建的会话返回的凭证;使用他人的凭证会返回 404 asset_not_found。

第四步:提交真人素材

POST /?Action=CreateAsset&Version=2024-01-01

拿到 GroupId 后,用与虚拟人像相同的 CreateAsset / GetAsset 提交并轮询素材(字段与状态说明见虚拟人像素材)。

每次提交会进行人脸一致性校验(与认证人物比对),校验不通过无法入库。同一素材组只能提交同一人物的素材。

状态说明

• Processing — 素材已提交,正在审核 / 一致性校验中。
• Active — 素材已可用,可在视频生成接口中以 asset://<ASSET_ID> 引用(方式同虚拟人像素材)。
• Failed — 处理失败。常见原因:素材与认证人物不一致、模糊 / 遮挡 / 多人同框、URL 不可访问。

常见失败原因

• H5 链接过期(认证会话 30 分钟内有效),被拍摄者未及时完成认证
• 认证尚未完成就调用 GetVisualValidateResult
• 使用了他人创建的认证会话凭证(404 asset_not_found)
• 提交的素材与认证人物不一致,一致性校验不通过
• 素材 URL 无法访问或质量过低