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

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

支持范围

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

模型	已集成官方 H5 渠道	APIMart / APIB	VideoFee	其它渠道
seedance-2.0	有能力适配；需配置、权限、项目及该模型路由可用	已有素材库；当前集成无真人 H5	渠道素材审核；无官方本人 H5	尚未核实
seedance-2.0-fast	同上	同上	同上	尚未核实
seedance-2.0-mini	同上	同上	同上	尚未核实
seedance-2.5	同上	同上	同上	尚未核实

官方 H5 适配包含火山 Ark 与 BytePlus。是否可用取决于渠道配置、账号权限、项目和模型路由，请先查询能力接口。配置 AK/SK 不等于账号权益已开通；明确选择不支持的渠道会拒绝，不自动切换。

官方权益区分基础免费权益与高级创作权益：基础免费权益仅支持控制台真人认证；免费高级 Entry 列明支持真人 Assets API。请由渠道运营方确认对应 API 权益，平台不会自动开通、签署协议或购买权益。

生成限制	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、live_acceptance。official_h5 是接口能力，不代表某个客户已经通过认证；real_person_verified=false 不代表认证会话失败。当前集成没有已核实的渠道自有合法真人授权流程；不要将一般素材审核推定为该能力。

渠道素材审核（VideoFee）

能力接口返回 method=channel_material_review 时，使用渠道素材流程。official_h5 与此流程分开；渠道审核 Active 表示素材可用，不代表已完成火山官方本人活体认证。仅提交本人已明确授权的照片。

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\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"purpose\":\"channel_portrait\",\"name\":\"授权人像素材\"}"

保存返回的公开组 data.id，按下文受控上传、提交素材和逐项查询的接口继续操作。该组为 group_type=channel_portrait，是平台管理组，不能作为官方真人 GroupId。普通素材使用 purpose=ordinary；这两个用途当前只用于支持该流程的 VideoFee 渠道。省略 purpose 的旧请求继续保持原有行为，旧组不会批量改成已认证真人组。

认证由渠道后台执行，无本人 H5 链接。素材响应包括 verification_method=channel_material_review、owner_verified=false、material_purpose 和 review。review.scope_model 表示素材关联模型。只有 Active 可引用；上传完成和 Processing/Pending 均不能视为审核通过。跨模型认证兼容性尚无明确依据时，接口返回不兼容错误，不自动换路由或重复上传。

渠道真人素材提交及引用生成需要 Idempotency-Key。生成继续使用现有报价、预扣和结算接口；超时先查询原任务，不自动重复 POST。素材删除仅删除 APIMaster 管理记录，上游没有公开删除接口的部分不能承诺同时删除。

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 默认创建虚拟组；VideoFee 的显式 purpose=ordinary 或 channel_portrait 分别创建普通或渠道人像素材管理组，均不能作为官方本人认证证明。旧组不批量升级为真人组。

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 组中的每项图片由上游做同人一致性审核，审核失败不等于缺少本人认证。channel_portrait 组执行渠道素材审核，其结果不作为官方同人一致性或本人活体认证证明。

提交返回公开 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 小时，持链接者可访问；私有目录文件权限 0600，24 小时后访问拒绝，每小时清理过期文件，因此物理删除最迟约 25 小时。
• DELETE /v1/seedance2/private-avatar/uploads/{upload_id} 删除本人的托管原件，签名 URL 立即无法下载。不会删除已经审核入库的上游素材；入库未完成时删除原件可能导致下载/审核失败。
• DELETE /v1/seedance2/private-avatar/assets/{asset_id} 删除平台记录，并在渠道支持时执行上游删除；VideoFee 当前仅删除平台记录，不删除上游资产。非空组须先删除各资产，再 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 教程及四模型比较。