Seedance 本人认证与同人素材入库

SD2.0、Fast、Mini 与 SD2.5 共用的托管认证、审核与资产引用流程。

Seedance 本人认证与同人素材入库

普通图片、视频和音频使用统一素材库。创建素材组时只传模型和名称，不传 channel_id 或 purpose；后台按目标模型管理审核与素材副本。

重要提示：明星与普通素人使用不同接口

只有明星才需要使用真人接口，发起本人活体认证：POST /v1/seedance2/private-avatar/verifications。

普通素人直接使用素材接口提交素材审核：POST /v1/seedance2/private-avatar/assets，不要使用真人接口，也不要创建本人活体认证会话。素材达到 Active 后即可引用。

本文描述本版本的共用接口；是否可用取决于所选渠道配置和账号权益。官方 H5 本人认证必须由照片中的本人在手机完成，不能通过服务端自动代做；渠道素材审核按其后台审核流程执行。普通素材审核、虚拟人像审核、渠道自动审批均不等于官方本人认证。

支持范围

四个公开模型共用认证和素材管理模块，各自保留生成协议。SD1.0、SD1.5、自定义别名不自动套用真人认证；需按精确上游模型另行核对。

模型	APIMaster 认证与素材接口	可用能力
seedance-2.0	共用本文接口	以能力查询返回结果为准
seedance-2.0-fast	共用本文接口	以能力查询返回结果为准
seedance-2.0-mini	共用本文接口	以能力查询返回结果为准
seedance-2.5	共用本文接口	以能力查询返回结果为准

客户只使用 APIMaster 的鉴权、公开会话／组／素材 ID 和本文接口。上游接口路径、凭证、资产 ID 及审核状态由后台适配；不需要按供应商编写不同请求。channel_id 是 APIMaster 的路由标识，用于绑定素材上下文，不是上游账号或资产 ID。可用性由 APIMaster 后台配置、权限、项目及模型路由共同确定，请先查询能力接口。账号权益与上游凭证由平台管理；缺少所需能力或权益时返回明确错误，不自动切换渠道、开通权益或购买权益包。

生成限制	SD2.0 / Fast / Mini	SD2.5
时长	4–15 秒，自动时长按该模型接口	4–30 秒，或 -1
图片参考	最多 9 张	最多 30 张
视频参考	最多 3 段，合计不超过 15 秒	最多 10 段，合计不超过 30 秒
音频参考	最多 3 段，需图片/视频，合计不超过 15 秒	最多 10 段，合计不超过 30 秒
分辨率、编辑和其它参数	见各模型文档及选中渠道协议	见 SD2.5 文档；不能直接套给 SD2.0

入库限制与生成输入限制不同。审核 Active 后换模型，仍须再次校验输入类型、数量、时长、分辨率和角色。已批准素材只在兼容渠道、账号和项目中复用；不因切换模型重复认证，新增照片仍须同人审核。

1. 查询模型和渠道能力

所有客户接口使用 APIMaster Bearer Key。上游 AK/SK、BytedToken、原始 GroupId 和 AssetId 均由服务端管理。

export APIMASTER_KEY='<你的 APIMaster Key>'
export APIMASTER_CHANNEL_ID='<能力接口返回的可用渠道 ID>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/capabilities?model=seedance-2.5' \
  -H "Authorization: Bearer $APIMASTER_KEY"

data 数组包含 model、channel_id、method、configured、reason、hosted_callback、real_person_verified。official_h5 是接口能力，不代表某个客户已经通过认证；real_person_verified=false 不代表认证会话失败。当前集成没有已核实的渠道自有合法真人授权流程；不要将一般素材审核推定为该能力。

统一素材审核：创建、保存和复用

普通图片、视频和音频使用统一素材库。创建素材组时只传模型和名称，不传 channel_id 或 purpose；后台按目标模型管理审核与素材副本。

export APIMASTER_KEY='<your APIMaster key>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/groups' \
  -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"seedance-2.5","name":"My materials"}'

asset_type: Image / Video / Audio.

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
  -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unified-audio-001' \
  -d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Audio","assets":[{"url":"https://your-storage.example/audio.mp3","name":"Reference audio"}]}'

保存建组返回的 data.id（提交时作为 group_id）、asset_id 和 asset_url（asset:// 引用）。通过素材接口主动提交审核，查询任务及 available_models、model_readiness，确认目标模型就绪后再生成。同一个素材 ID 可在以后复用；删除、过期或补建副本时仍须确认素材和原文件可用。官方 H5 本人认证是单独流程，不是普通素材送审的前置步骤。

2. 官方本人认证：创建会话并在手机完成 H5

本节仅适用于明星。普通素人请跳过本人活体认证，直接进入素材提交审核流程。

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications' \
  -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: portrait-session-001' \
  -d "{\"model\":\"seedance-2.5\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"name\":\"本人肖像\"}"

channel_id 请使用能力查询中实际可用的渠道，不照抄示例。model 必须是四个公开 ID 之一。可选 name 最大 64 字符。不传 callback_url，首期只接受平台托管回调；旧的自定义回调请求将返回 400。认证会话需要 8–128 字符的 Idempotency-Key。同一用户、同一幂等键返回原会话；不同内容返回 409。每用户每分钟最多创建 3 次；上游账号限流仍可能返回错误。

成功响应 data 至少包含：

{
  "id":"verification_PUBLIC_ID",
  "session_id":"verification_PUBLIC_ID",
  "object":"seedance.avatar.verification",
  "model":"seedance-2.5",
  "method":"official_h5",
  "status":"pending",
  "created_at":1791374400,
  "expires_at":1791376200,
  "verification_url":"<官方返回的敏感 H5 链接>",
  "h5_link":"<同一链接>"
}

本人打开 H5 链接完成授权和认证。链接可能含临时授权参数，只私下发送给本人手机，不公开分享、截图或写入日志。控制台 /console/seedance-materials 提供创建链接、复制到手机、查询确认、上传和审核入口。Key 仅保存在页面内存，不保存到浏览器存储。

官方认证凭证查询期限为 30 分钟；H5 链接使用后失效。响应的 expires_at 是本次会话凭证查询截止时间，不是人物素材授权到期时间。平台收到匹配回跳后停止返回 H5 链接；本人使用后但没有点击回跳时，平台不能独立知道链接是否已经消耗。

3. 平台回调与服务端确认

上游 CallbackURL 使用 APIMaster HTTPS 页面，客户无需自建服务器。回调绑定不可猜测的关联标识并比对本次凭证，之后服务端调用 GetVisualValidateResult。浏览器声明 resultCode=10000 不能自行创建真人组。重复回调不重复创建组，不发起资产上传。

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications/verification_PUBLIC_ID' \
  -H "Authorization: Bearer $APIMASTER_KEY"

状态：creating、pending、completed、failed（已知权益不足）、expired、failed_unconfirmed、submission_unknown。

completed：服务端确认并返回公开 group_id，H5 链接不再返回。
failed_unconfirmed：匹配回跳报告失败，但服务端尚未取得组；这是待确认失败提示，不是平台伪造的官方认证结论。可查询原会话。
expired：凭证查询窗口到期。没有自动重新创建；需本人明确启动新会话。
submission_unknown：创建调用超时、错误或无有效响应，受理结果未确认。保留原会话 ID，不重复 POST，不自动新建；交给支持人员对账。
网络暂时失败：查询返回安全错误，原会话保持原状态。退出或不回跳的会话可一直待完成，至窗口到期。

官方认证成功后得到公开 group_id，对应 group_type=real_person。普通素材通过 POST /groups 创建 group_type=unified_virtual 的统一素材组；素材审核不能作为官方本人认证证明。

4. 共用素材提交接口与查询 Active

普通素人使用本节的素材提交接口即可，不需要先调用真人认证接口。

普通／虚拟素材、官方真人组素材和渠道人像素材均提交到同一 POST /v1/seedance2/private-avatar/assets，由所选组及其渠道确定审核流程。旧 POST /v1/seedance2/private-avatar 是同一提交处理逻辑的兼容入口，不是另一个真人认证接口。POST /uploads 仅托管原件，不会创建上游素材或完成认证。

优先上传到平台受控存储：

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/uploads' \
  -H "Authorization: Bearer $APIMASTER_KEY" -F 'file=@approved-owner.png'

仅使用明确获授权的本人照片。支持 JPEG/PNG，最大 10 MB。返回 upload_id、敏感 url、url_expires_at、delete_after。将 url 私下传给资产提交接口：

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
  -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: portrait-image-20261007-001' \
  -d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Image","assets":[{"url":"<刚获取的签名 URL>","name":"本人正面"}]}'

也可使用自己受控存储的可下载限时 URL。勿默认上传到长期公开图床。真人组的素材提交必须有幂等键；不要根据文件名或审核任务 ID 推造 asset_id。官方 real_person 组中的每项图片由上游做同人一致性审核，审核失败不等于缺少本人认证。旧素材组仍执行渠道素材审核，其结果不作为官方同人一致性或本人活体认证证明。

提交返回公开 asset_task_*，随后查询：

curl --fail-with-body 'https://apimaster.ai/v1/tasks/asset_task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"

Processing / Pending 仍不可生成；Failed 无法生成；只有 Active 可引用。部分通过时保留已通过素材。批次中途超时返回 submission_unknown 并保留已受理 ID；单项查询可确认已受理素材。没有上游 ID 的项不能盲目重传，需支持对账。所有资源查询均按发起用户隔离。

5. 引用、查询和下载视频

视频生成按所选模型及渠道计费。先调用 /v1/videos/quote 获取报价并确认预算，再提交生成任务。报价不是系统保证的最高收费金额。

curl --fail-with-body 'https://apimaster.ai/v1/videos' \
  -H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: owner-video-20261007-001' \
  -d '{"model":"seedance-2.5","prompt":"人物自然微笑，保持本人外观","image_urls":["asset://asset_PUBLIC_ID"],"resolution":"480p","duration":4,"generate_audio":false}'

引用真人资产生成需要幂等键。先持久化独立 video_request_* 受理记录和 task_* 公开视频 ID，再走现有报价、预扣、结算和回执链路。响应头 X-Seedance-Request-Id 用于查询受理记录；重复请求返回 202 和原受理记录，不再提交收费任务；同键改内容返回 409。真人素材生成禁用自动重试，包括上游受理结果不确定时的 POST 重试。受理记录与认证会话、审核任务、组、资产和视频任务 ID 分开。

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/video-requests/video_request_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/billing' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/content' -H "Authorization: Bearer $APIMASTER_KEY" -o owner-video.mp4

受理状态 submission_unknown 表示尚未找到持久化视频任务；不要因查询 404 就重跑。只有确认受理且任务成功才下载。失败退款继续按现有任务回执及账务规则处理，不以回调费用标志替代账单核验。

隐私、存储、删除与费用

本地照片只是托管原件，与上游 Asset 分开。原件签名 URL 有效 1 小时，持链接者可访问；24 小时后访问拒绝，最迟约 25 小时内删除。
DELETE /v1/seedance2/private-avatar/uploads/{upload_id} 删除本人的托管原件，签名 URL 立即无法下载。不会删除已经审核入库的上游素材；入库未完成时删除原件可能导致下载/审核失败。
DELETE /v1/seedance2/private-avatar/assets/{asset_id} 删除平台记录，并在渠道支持时执行上游删除；若上游未提供删除能力，仅删除平台记录，不能承诺删除上游资产。非空组须先删除各资产，再 DELETE /groups/{group_id}。平台映射或上游素材删除后，原公开素材 ID 不能继续作为生成引用，已生成成片也不会因删除原件自动消失。
人物授权期限与资产保留由上游规则及本人授权决定；没有推造授权有效期，也不承诺上游未提供的授权撤销能力。未实现单独授权撤销 API。平台不保存人脸特征或生物识别模板。
2026-10-07 核对的火山官方文档称真人认证服务限时免费；没有核实当前各渠道实际认证、同人审核、上传、存储、管理账单。APIMaster 此流程未新增素材费用扣款逻辑，但不能由此承诺上游永久免费。账号权益由运营预先核实，平台不会自动购买。
视频仍按模型、分辨率、时长、输入内容计费；以市场卡、quote 和实际 billing 回执核实。手机认证费用标志仅供提示，不是已核账证据。
错误通过 HTTP 400/403/404/409/429/502/503 区分输入或回调不匹配、权限、资源不存在、未认证/未 Active/作用域不兼容、限流和上游不可确认；支持追踪会话 ID、审核任务 ID、视频受理 ID。

官方参考文档

核查日期：2026-10-07。接口字段与状态依据官方文档，渠道实际支持另行核查：真人库指南、拉起真人认证 H5、获取真人组、创作权益、CreateAsset、GetAsset、创建视频任务、SD2.5 教程及四模型比较。

Seedance 幂等提交与异常恢复

统一虚拟素材与自动恢复

新建虚拟组不指定 channel_id 时，可通过同一个 asset:// ID 使用兼容模型。available_models、model_readiness、all_models_ready 表示就绪情况；一个服务的审核通过不代表其他服务也通过。查询审核任务刷新状态；补齐副本需要原件仍可访问。显式指定渠道、旧素材组及官方 H5 认证素材仍受各自绑定限制。

生成需携带 Idempotency-Key。只有收到明确的限流拒绝且未返回任务 ID 时，才可能在提交阶段尝试兼容服务。已受理任务若以明确的账号停用、凭证失效或服务故障终止，在存在可用兼容服务时，平台最多自动恢复一次。恢复沿用原公开任务 ID 和冻结的用户计费价格，不新增一笔生成预扣；继续查询原任务及其计费回执。

恢复引用素材前，目标服务必须已有兼容且审核通过的副本，或完成独立素材审核；不能沿用其他服务的审核结论。官方 H5 认证不会自动跨账号复制。参数、内容审核、版权错误，以及超时、断连或受理不明，不属于自动恢复范围。未满足条件时不会强行切换。需要手动重新提交时，先查询受理回执，只有 new_submission_safe=true 才可使用新键。