豆包真人素材使用指南

真人素材用于在视频中引用已由本人确认的人物形象。流程为：创建素材组、本人完成网页确认、添加素材、等待素材可用，再提交视频生成任务。本页以图片素材为例，使用 AIHubMix API 完成素材管理，优先使用新版 /ai/v1/videos 生成视频。已有 /v1/videos 客户端可参考兼容协议示例。

前置条件

准备有效的 AIHubMix API Key，通过环境变量 AIHUBMIX_API_KEY 读取。
使用新版视频接口前，在控制台开启异步任务，并确认账户有足够额度及目标模型的使用权限。
素材中的本人同意相关用途，并亲自完成网页上的确认流程。同一素材组仅添加同一人的素材。
准备可供模型推理厂商读取的图片直链，确认链接在素材处理期间持续有效。
命令行示例需要 Bash、curl 和 jq。在同一终端按步骤执行，保留返回的素材组、确认会话、素材和视频任务 ID。

BytePlus 官方真人素材指南覆盖 Seedance 2.0 和 Seedance 2.5。本页新版视频主示例使用已完成线上验证的 AIHubMix 模型 ID doubao-seedance-2-5-260628；具体版本、参考媒体类型和参数以当前模型 Schema 及账户可用能力为准。验证范围见本次流程验证，不要据此推定所有 Seedance 版本均可使用真人素材。

准备终端环境，API Key 应已由你的运行环境注入：

set -euo pipefail
: "${AIHUBMIX_API_KEY:?请先配置 AIHUBMIX_API_KEY 环境变量}"
BASE_URL="https://aihubmix.com"
MODEL="doubao-seedance-2-5-260628"

创建素材组

GROUP_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"我的真人素材"}')
printf '%s\n' "$GROUP_JSON" | jq .
GROUP_ID=$(printf '%s' "$GROUP_JSON" | jq -er '.id')

请求体只接受 name，名称不能为空，最长 100 个字符。创建成功返回 HTTP 201，初始状态为 pending_auth。素材组公开字段为 id、object、name、status、created_at、updated_at，其中 object 固定为 asset_group，时间字段为 Unix 秒。后续以 status=active 判断素材组已可添加素材。如果创建响应丢失，先查询列表，避免直接重复创建：

curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

列表返回 data、has_more、next_after。下一页传入 after=上一页的next_after；limit 默认 20，最大 100。名称不作为幂等标识，请结合 ID 和创建时间识别素材组。

获取本人确认链接

创建确认会话，无需请求体：

SESSION_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY")
SESSION_ID=$(printf '%s' "$SESSION_JSON" | jq -er '.id')
printf '%s' "$SESSION_JSON" | jq '{id, status, expires_at, verification_url}'

创建成功返回 HTTP 201。公开字段为 id、object、group_id、status、created_at、expires_at、completed_at；object 固定为 verification_session，时间字段为 Unix 秒，未完成时 completed_at 为 null。

verification_url 仅在成功创建响应中返回，后续查询不会再次返回链接。及时将链接交给素材中的本人，不要放入公开日志、代码仓库或反馈截图。有效期以 expires_at 为准，过期后不能继续使用原链接。

本人打开 verification_url，核对页面展示的主体与用途，阅读并确认相关条款，按页面提示完成操作。BytePlus 官方指南说明此过程需要登录个人 BytePlus 账户；页面需要相机权限时，由本人操作设备并授权。官方页面可能包含素材上传等步骤，按实际提示完成。本页接下来的 API 素材创建步骤仍需执行，并取得 AIHubMix 返回的素材 ID；不要把网页显示的其他素材 ID 直接代入 API 示例。

查询确认结果

curl --fail-with-body -sS "$BASE_URL/ai/v1/verification-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

会话状态	下一步
`creating`	会话仍在创建，稍后查询；持续未完成时联系支持
`pending`	等待本人完成或结果确认，稍后继续查询
`verified`	本人确认已完成，继续核对素材组为 `active`
`rejected`	本次未通过，检查网页提示后重新发起
`expired`	本次已过期，重新发起确认
`failed`	本次失败，检查错误提示，必要时联系支持

客户端可每 10 至 15 秒查询一次，并设置本地等待上限。该间隔为使用建议。网页显示完成或返回空白页面时，仍应通过 API 确认会话为 verified、素材组为 active，再添加素材。若重新创建返回 409 verification_session_active，先查询已有会话和素材组。有效会话仍存在、素材组已完成确认，或前次结果仍待确认时，都不应反复新建。持续未完成时联系支持。

网页出现 internal error 不代表确认会话已结束。先执行本节的两个 GET 请求，查询会话和素材组；会话仍为 pending 时，不要反复创建同组会话。只有会话为 verified 且素材组为 active，才继续添加素材。仅凭网页错误无法判断原因，持续未完成时保留 ID 联系支持。

通过图片地址创建素材

图片准备

提供返回图片文件的绝对 HTTP(S) 地址，优先使用 HTTPS。链接应无需登录或附加请求头即可读取；本地路径、内网地址、Base64 和带账号密码的 URL 不适用于素材创建接口。URL 不应包含 # 片段。根据 BytePlus 真人素材指南，图片建议为清晰正面照，并符合以下素材入库要求：

项目	要求
格式	JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF
单张大小	小于 30 MB
宽高比	大于 0.4、小于 2.5
宽和高	均大于 300 像素、小于 6000 像素
人物	与该素材组完成确认的人物一致

上述为官方素材库要求，视频模型还可能有独立的参考素材限制。上传前同时核对目标模型要求；HTTP 创建成功也不表示素材已通过处理。

创建请求

将 IMAGE_URL 改为你已获得本人同意使用的图片直链。示例域名仅作占位，不提供真人图片。

IMAGE_URL="https://cdn.example.com/portrait.jpg"
ASSET_KEY="portrait-image-001"
ASSET_BODY=$(jq -n --arg url "$IMAGE_URL" --arg ref "$ASSET_KEY" \
  '{url: $url, asset_type: "image", client_reference_id: $ref}')
ASSET_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ASSET_KEY" \
  -d "$ASSET_BODY")
printf '%s\n' "$ASSET_JSON" | jq .
ASSET_ID=$(printf '%s' "$ASSET_JSON" | jq -er '.id')

请求字段	必填	说明
`url`	是	可访问的素材文件地址
`asset_type`	是	`image`、`video` 或 `audio`；本例使用 `image`
`client_reference_id`	否	业务侧素材标识，最长 128 字节

请求体只接受以上三个字段。Idempotency-Key 放在请求头，可选，最长 128 字节，不能有首尾空白或控制字符。音视频的文件限制请查阅上述官方指南，并核对目标模型支持的类型与时长。首次创建通常返回 HTTP 201；复用已有素材返回 200；结果仍待确认、状态为 reconciling 时返回 202。始终读取对象的 status。素材公开字段为 id、object、group_id、asset_type、status、client_reference_id、created_at、updated_at、deleted_at。object 固定为 asset；未提供或已删除的 client_reference_id 不返回，未删除时 deleted_at 为 null。时间字段为 Unix 秒，查询不返回原图片地址，请自行保留业务记录。

等待素材可用

curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

素材状态	含义与处理
`creating`	创建尚未完成，保留 ID 并稍后查询
`processing`	正在处理，继续查询
`active`	可作为视频参考素材
`failed`	素材处理失败，检查图片及人物一致性要求
`reconciling`	创建或删除结果仍待确认，继续查询，暂不用于视频
`deleting`	删除处理中，暂不用于视频
`deleted`	删除已完成，不再用于视频

可每 10 至 15 秒查询一次，并设置本地等待上限。停止本地轮询不会取消服务端操作。

创建结果未知且持续没有匹配结果时，素材可能一直保持 reconciling，也可能影响素材或素材组删除。保留 ID 和原请求标识，联系支持；不要通过更换标识反复创建，也不要假设等待一段时间就会自动清理。

使用素材生成视频

视频引用使用 AIHubMix 素材创建响应中的完整 id，格式为 asset://<asset_id>。同一次请求引用的全部素材必须属于同一素材组、归当前账户所有，且均为 active。素材组也必须保持可用。

素材类型	新版 `input_references[].type`	兼容版嵌套字段
`image`	`image_url`	`image_url.url`
`video`	`video_url`	`video_url.url`
`audio`	`audio_url`	`audio_url.url`

引用类型必须与素材创建时的 asset_type 一致。asset:// 用于视频参考字段，不是供浏览器下载的地址。

新版视频协议

先按端点路径核对当前模型 Schema：

curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'

确认模型支持参考图片后提交。以下采用本次线上验证成功的 Seedance 2.5 参数：duration=4、resolution="480p"、aspect_ratio="3:4"、generate_audio=false。新版直接使用 input_references[].url，其中 ASSET_ID 为前面 AIHubMix 返回的素材 ID：

VIDEO_BODY=$(jq -n --arg model "$MODEL" --arg asset "asset://$ASSET_ID" \
  '{model: $model,
    prompt: "The person in the reference image smiles and waves at the camera.",
    duration: 4,
    resolution: "480p",
    aspect_ratio: "3:4",
    generate_audio: false,
    input_references: [{type: "image_url", url: $asset}]}')
VIDEO_JSON=$(curl --fail-with-body -sS --max-time 120 \
  -X POST "$BASE_URL/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$VIDEO_BODY")
printf '%s\n' "$VIDEO_JSON" | jq .
VIDEO_ID=$(printf '%s' "$VIDEO_JSON" | jq -er '.id')
export VIDEO_ID

新版使用整数 duration 表示请求时长；其他允许值以模型 Schema 为准。resolution="480p" 是请求的分辨率档位，不保证输出宽或高固定为 480 像素，实际尺寸以生成文件为准。首尾帧可使用 frame_images[].image_url.url，同时设置 frame_type，仅在模型支持相应能力时使用。完整参数参阅视频生成。

兼容视频协议

已有客户端使用 /v1/videos 时，将引用放在 content 或 extra_body.content，URL 嵌套在相应媒体对象内。本例选用 extra_body.content：

兼容示例保留 doubao-seedance-2-0-260128，依据现有兼容接口约定和 BytePlus 官方素材引用说明编写。本次未实测 Seedance 2.0 视频生成及 /v1/videos 兼容创建，不能将新版 Seedance 2.5 的验证结果直接用于该示例。

COMPAT_MODEL="doubao-seedance-2-0-260128"
COMPAT_BODY=$(jq -n --arg model "$COMPAT_MODEL" --arg asset "asset://$ASSET_ID" \
  '{model: $model,
    prompt: "The person in the reference image smiles and waves at the camera.",
    extra_body: {content: [{type: "image_url", image_url: {url: $asset}, role: "reference_image"}]}}')
curl --fail-with-body -sS --max-time 120 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$COMPAT_BODY" | jq .

两种示例择一执行，每次视频创建都是独立请求。不要在兼容请求中混入 input_references。同时提供两处 content 时，extra_body.content 覆盖顶层 content，建议只提供一处。兼容版返回的 id 应用于 GET /v1/videos/{id} 查询，完成后通过 GET /v1/videos/{id}/content 下载。不要把兼容版 ID 交给 /ai/v1/videos 查询。详细说明见兼容视频接口。

轮询并下载新版视频

以下 Python 示例仅接续前面的新版创建步骤，读取环境变量中的 VIDEO_ID，不重新创建任务。需要安装 requests。

import os
import time
from pathlib import Path

import requests

base_url = "https://aihubmix.com"
video_id = os.environ["VIDEO_ID"]
headers = {"Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}"}
deadline = time.monotonic() + 1800

while time.monotonic() < deadline:
    response = requests.get(
        f"{base_url}/ai/v1/videos/{video_id}", headers=headers, timeout=30
    )
    response.raise_for_status()
    task = response.json()
    status = task["status"]
    if status == "completed":
        break
    if status in {"failed", "cancelled"}:
        raise RuntimeError(f"视频任务未完成：{task.get('error') or status}")
    time.sleep(15)
else:
    raise TimeoutError(f"本地等待已结束，请稍后继续查询原任务：{video_id}")

temporary = Path("result.mp4.part")
with requests.get(
    f"{base_url}/ai/v1/videos/{video_id}/content",
    headers=headers,
    timeout=120,
    stream=True,
) as response:
    response.raise_for_status()
    with temporary.open("wb") as output:
        for chunk in response.iter_content(chunk_size=1024 * 1024):
            if chunk:
                output.write(chunk)
temporary.replace("result.mp4")
print("视频已保存为 result.mp4")

30 分钟为示例的本地等待上限，不代表服务端任务超时。查询 HTTP 200 不代表生成成功，必须检查 status。轮询使用 /ai/v1/videos/{id}，统一任务接口 /ai/v1/tasks/{id} 提供只读快照。视频查询和下载使用创建任务时的同一 API Key。完成后及时下载并自行保存；结果有保留期，以 expires_at 为准，过期可能返回 410 artifact_expired。

本次流程验证

2026-09-07 的线上验证使用公网 HTTPS JPEG 直链、本人完成的网页确认，以及上述 Seedance 2.5 参数，观察到以下结果：

步骤	本次结果
创建素材组	HTTP `201`，`status=pending_auth`
创建确认会话	HTTP `201`，`status=pending`
本人完成确认后查询	会话 HTTP `200`、`status=verified`，素材组为 `active`
创建并查询图片素材	创建 HTTP `201`、`status=processing`，后续查询 HTTP `200`、`status=active`
创建并查询新版视频	创建 HTTP `200`、`status=in_progress`，后续查询 HTTP `200`、`status=completed`、`error=null`
下载视频	HTTP `200`，`Content-Type: video/mp4`，文件通过 ffmpeg 完整解码

本次文件为 1,558,358 字节；ffprobe 检测为 H.264、24 fps、560 × 752 像素、4.041667 秒、无音轨。这些数值为该次生成结果，不代表每次请求都会输出相同尺寸、时长或文件大小。首次打开确认页面曾出现 internal error，随后 API 查询仍为 pending，页面错误的原因尚未确认。该次测试随后使用独立测试组的新页面，由本人完成操作后确认会话为 verified、素材组为 active。新组仅是本次测试的处理方式，不作为反复重建素材组的通用建议，也不表示原会话已结束。本次未实测 Seedance 2.0 视频生成、兼容接口创建、音视频素材、首尾帧、删除及其他异常组合。相关说明保留接口约定和官方资料依据，本次验证不覆盖整篇指南的全部场景。

幂等重试

素材创建超时或响应丢失时，保留原 Idempotency-Key、client_reference_id、URL 和 asset_type，重发同一请求。两个标识中任一个命中同一账户、同一素材组的已有素材时，会复用该素材。
相同标识对应的 URL 或 asset_type 发生变化时，返回 409 asset_idempotency_conflict。带签名的图片 URL 更新后也属于 URL 变化。
未提供任一标识时，不保证跨请求去重。只有确认要创建另一份素材时，才使用新标识。
已取得素材 ID 后，优先用 GET /ai/v1/assets/{id} 查询。reconciling 不等于失败，不应改用新标识再创建。
素材删除完成后，原幂等标识不再保留。不要依赖它找回已删除素材，也不要重放旧创建请求。
本节幂等约定仅适用于素材创建。素材组、确认会话和视频创建不能套用该约定。新版视频创建响应丢失时，先用 GET /ai/v1/videos?limit=20&order=desc 查找原任务，避免重复生成。

删除素材和素材组

删除前先确认所有引用该素材的视频均已结束，包括通过兼容接口提交的任务。删除操作不能撤销，已下载的视频文件需自行管理。删除单个素材：

curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

返回 202 表示删除仍在处理，通过 GET /ai/v1/assets/{id} 继续查询，直到 status=deleted。重复删除返回当前状态；若为 reconciling，继续确认结果，持续未完成时联系支持。删除整个素材组会同时删除组内素材，必须显式传入 cascade=true：

curl --fail-with-body -sS -X DELETE \
  "$BASE_URL/ai/v1/asset-groups/$GROUP_ID?cascade=true" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

受理后返回 202，通过 GET /ai/v1/asset-groups/{id} 查询。deleting 表示处理中，partially_deleted 表示尚未全部删除，deleted 才表示完成。列表默认不展示已删除素材组。 409 asset_group_in_use 表示仍有操作或视频任务未结束。等待并查询相关状态后重试。兼容视频任务需要自行确认结束，不要依赖删除请求自动判断所有兼容任务的占用。

常见问题

已完成网页操作，为什么还不能添加素材？

先查询确认会话和素材组，以 verified 和 active 为准。网页出现 internal error 时也执行相同检查；pending 期间不反复创建同组会话。结果尚未确认时稍后再查；持续未完成请提供 ID 联系支持，无需提交确认链接或本人照片。

素材可用，为什么生成视频仍然失败？

检查引用是否使用 AIHubMix 返回的素材 ID，所有素材是否属于同一组，媒体类型是否匹配，以及当前模型是否支持相应输入。素材 active 表示素材可用，视频任务仍需单独检查完成状态和错误信息。

如何处理常见接口错误？

HTTP	`error.code`	处理方式
400	`invalid_request`	检查请求字段、结构和所用视频协议
400	`asset_group_invalid`	检查素材组名称
400	`asset_invalid`	检查 URL、素材类型和请求标识
400	`asset_binding_mismatch`	同一次视频请求只引用同一素材组的素材
400	`cascade_confirmation_required`	确认整组删除意图后传入 `cascade=true`
401	`authentication_failed`	检查 API Key 环境变量及认证请求头
403	`async_not_enabled`	开启异步任务后使用新版视频接口
404	`asset_group_not_found`、`asset_not_found`、`verification_session_not_found`	检查资源 ID 和所属账户
409	`asset_group_not_verified`	查询本人确认结果，等待素材组可用
409	`verification_session_active`	查询已有会话或素材组，避免重复发起
409	`asset_not_ready`	查询素材状态，生成视频前等待 `active`
409	`asset_idempotency_conflict`	核对标识对应的原 URL 和类型
409	`asset_group_in_use`	等待相关操作、视频任务结束后再删除
503	`asset_group_unavailable`、`verification_unavailable`、`asset_unavailable`	稍后重试；持续不可用时联系支持

其他视频错误参阅异步任务错误码。反馈时提供发生时间、HTTP 状态、error.code、返回的 error.tid（如有）及相关资源 ID；不要提供 API Key、确认链接或带签名的图片地址。

参考资料

更新时间：2026-09-07

开始使用

网关能力

模型能力

协议参考

平台管理

隐私和条款

豆包真人素材使用指南

前置条件

创建素材组

获取本人确认链接

查询确认结果

通过图片地址创建素材

图片准备

创建请求

等待素材可用

使用素材生成视频

新版视频协议

兼容视频协议

轮询并下载新版视频

本次流程验证

幂等重试

删除素材和素材组

常见问题

已完成网页操作，为什么还不能添加素材？

素材可用，为什么生成视频仍然失败？

如何处理常见接口错误？

参考资料

​前置条件

​ 创建素材组

​ 获取本人确认链接

​ 查询确认结果

​ 通过图片地址创建素材

​图片准备

​创建请求

​ 等待素材可用

​ 使用素材生成视频

​新版视频协议

​兼容视频协议

​ 轮询并下载新版视频

​本次流程验证

​幂等重试

​删除素材和素材组

​常见问题

​已完成网页操作，为什么还不能添加素材？

​素材可用，为什么生成视频仍然失败？

​如何处理常见接口错误？

​参考资料

前置条件

创建素材组

获取本人确认链接

查询确认结果

通过图片地址创建素材

图片准备

创建请求

等待素材可用

使用素材生成视频

新版视频协议

兼容视频协议

轮询并下载新版视频

本次流程验证

幂等重试

删除素材和素材组

常见问题

已完成网页操作，为什么还不能添加素材？

素材可用，为什么生成视频仍然失败？

如何处理常见接口错误？

参考资料