> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Doubao Real-Person Assets Guide > Create real-person assets through personal web verification, reference them with asset:// for Doubao Seedance video generation, and query, retry, and delete assets. Real-person assets let you reference a person's likeness in videos after that person has completed verification. The workflow is to create an asset group, have the person complete web verification, add assets, wait for the assets to become available, and then submit a video generation task. This page uses image assets as an example and manages assets through the AIHubMix API, with the new `/ai/v1/videos` endpoint as the preferred option for video generation. Existing `/v1/videos` clients can refer to the [compatibility protocol example](#compatible-video).

Prerequisites

* Prepare a valid AIHubMix API Key and read it from the `AIHUBMIX_API_KEY` environment variable. * Before using the new video API, enable [async tasks](/en/api/async-tasks) in the console and confirm that your account has sufficient balance and permission to use the target model. * The person depicted in the assets must consent to the intended uses and personally complete the verification process on the web page. Add assets of only the same person to each asset group. * Prepare a direct image URL that the model provider can access, and ensure that it remains valid throughout asset processing. * The command-line examples require Bash, curl, and jq. Run the steps in the same terminal and retain the returned asset group, verification session, asset, and video task IDs. The official BytePlus real-person assets guide covers Seedance 2.0 and Seedance 2.5. The main example for the new video API on this page uses the AIHubMix model ID `doubao-seedance-2-5-260628`, which has been verified in production. Available versions, reference media types, and parameters depend on the current model Schema and the capabilities available to your account. See [Workflow Verification](#verified-flow) for the scope of verification; do not infer that all Seedance versions support real-person assets. Prepare the terminal environment. Your runtime environment should already have provided the API Key: ```bash theme={null} set -euo pipefail : "${AIHUBMIX_API_KEY:?请先配置 AIHUBMIX_API_KEY 环境变量}" BASE_URL="https://aihubmix.com" MODEL="doubao-seedance-2-5-260628" ```

1. Create an Asset Group

```bash theme={null} 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') ``` The request body accepts only `name`. The name must not be empty and can be up to 100 characters. Successful creation returns HTTP `201` with an initial status of `pending_auth`. The public asset group fields are `id`, `object`, `name`, `status`, `created_at`, and `updated_at`. The `object` value is always `asset_group`, and timestamps are in Unix seconds. Subsequently, use `status=active` to determine whether assets can be added to the group. If the creation response is lost, query the list first to avoid creating a duplicate group: ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` The list returns `data`, `has_more`, and `next_after`. For the next page, pass the previous page's `next_after` as `after`; `limit` defaults to `20` and has a maximum of `100`. Names are not idempotency identifiers. Use the ID and creation time together to identify an asset group.

2. Get the Personal Verification Link

Create a verification session without a request body: ```bash theme={null} 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}' ``` Successful creation returns HTTP `201`. The public fields are `id`, `object`, `group_id`, `status`, `created_at`, `expires_at`, and `completed_at`. The `object` value is always `verification_session`, timestamps are in Unix seconds, and `completed_at` is `null` until completion. `verification_url` is returned only in a successful creation response. Subsequent queries do not return the link again. Provide the link promptly to the person depicted in the assets, and do not include it in public logs, code repositories, or feedback screenshots. Its validity is determined by `expires_at`; the original link cannot be used after it expires. The person must open `verification_url`, check the entity and intended uses displayed on the page, read and accept the relevant terms, and follow the on-screen instructions. The official BytePlus guide states that this process requires signing in to a personal BytePlus account. If the page requests camera access, the person must operate the device and grant permission personally. The official page may include steps such as asset uploads; follow the actual prompts. You must still complete the API asset creation step below and obtain the asset ID returned by AIHubMix. Do not substitute other asset IDs shown on the web page directly into the API examples.

3. Check the Verification Result

```bash theme={null} 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 . ``` | Session status | Next step | | -------------- | ---------------------------------------------------------------------------------------------------- | | `creating` | The session is still being created. Query again later; contact support if it remains incomplete | | `pending` | Waiting for the person to complete verification or for the result to be confirmed. Query again later | | `verified` | Personal verification is complete. Also confirm that the asset group is `active` | | `rejected` | This attempt was not approved. Check the web page prompts before starting again | | `expired` | This attempt has expired. Start verification again | | `failed` | This attempt failed. Check the error message and contact support if needed | Clients can query every 10 to 15 seconds and set a local waiting limit. This interval is a usage recommendation. Even if the web page shows completion or returns a blank page, use the API to confirm that the session is `verified` and the asset group is `active` before adding assets. If another creation attempt returns `409 verification_session_active`, query the existing session and asset group first. Do not repeatedly create sessions while a valid session exists, the asset group has completed verification, or the previous result is still awaiting confirmation. Contact [support](/en/FAQs/Feedback) if the process remains incomplete. An `internal error` on the web page does not mean that the verification session has ended. First run the two GET requests in this section to query the session and asset group. Do not repeatedly create sessions for the same group while the session is still `pending`. Add assets only when the session is `verified` and the asset group is `active`. The web page error alone is insufficient to determine the cause. Retain the IDs and contact support if the process remains incomplete.

4. Create an Asset from an Image URL

Image Requirements

Provide an absolute HTTP(S) URL that returns an image file, preferably using HTTPS. The link should be accessible without login or additional request headers. Local paths, private network addresses, Base64, and URLs containing a username and password are not suitable for the asset creation API. The URL should not contain a `#` fragment. According to the [BytePlus real-person assets guide](https://docs.byteplus.com/en/docs/ModelArk/2315856), a clear, front-facing photo is recommended, and images must meet the following asset library requirements: | Item | Requirement | | ------------------- | -------------------------------------------------------------------- | | Format | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF | | File size per image | Less than 30 MB | | Aspect ratio | Greater than 0.4 and less than 2.5 | | Width and height | Both greater than 300 pixels and less than 6000 pixels | | Person | Must match the person who completed verification for the asset group | These are the official asset library requirements. Video models may have separate restrictions on reference assets. Also check the target model's requirements before uploading. A successful HTTP creation response does not mean that asset processing has succeeded.

Creation Request

Replace `IMAGE_URL` with a direct URL to an image that you have the person's consent to use. The example domain is a placeholder and does not provide a real-person image. ```bash theme={null} 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') ``` | Request field | Required | Description | | --------------------- | -------- | -------------------------------------------------------- | | `url` | Yes | An accessible URL for the asset file | | `asset_type` | Yes | `image`, `video`, or `audio`; this example uses `image` | | `client_reference_id` | No | An asset identifier in your application, up to 128 bytes | The request body accepts only these three fields. `Idempotency-Key` is an optional request header, up to 128 bytes, and must not contain leading or trailing whitespace or control characters. For audio and video file limits, consult the official guide linked above and check the types and durations supported by the target model. Initial creation usually returns HTTP `201`; reusing an existing asset returns `200`; when the result is still awaiting confirmation and the status is `reconciling`, the response is `202`. Always read the object's `status`. The public asset fields are `id`, `object`, `group_id`, `asset_type`, `status`, `client_reference_id`, `created_at`, `updated_at`, and `deleted_at`. The `object` value is always `asset`. A `client_reference_id` that was not provided or has been deleted is omitted, and `deleted_at` is `null` until deletion. Timestamps are in Unix seconds. Queries do not return the original image URL, so retain your own application records.

5. Wait for the Asset to Become Available

```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` | Asset status | Meaning and action | | ------------- | ------------------------------------------------------------------------------------------------------------------------ | | `creating` | Creation is incomplete. Retain the ID and query again later | | `processing` | Processing is in progress. Continue querying | | `active` | Available as a video reference asset | | `failed` | Asset processing failed. Check the image requirements and whether the person matches | | `reconciling` | The creation or deletion result is still awaiting confirmation. Continue querying and do not use the asset in videos yet | | `deleting` | Deletion is in progress. Do not use the asset in videos | | `deleted` | Deletion is complete. Do not use the asset in videos again | You can query every 10 to 15 seconds and set a local waiting limit. Stopping local polling does not cancel the server-side operation. If the creation result is unknown and no matching result is found over time, the asset may remain `reconciling` indefinitely. This may also affect deletion of the asset or asset group. Retain the ID and original request identifiers and contact support. Do not repeatedly create assets with different identifiers or assume they will be cleaned up automatically after some time.

6. Generate a Video Using the Asset

Video references use the complete `id` from the AIHubMix asset creation response in the format `asset://`. All assets referenced in a single request must belong to the same asset group, be owned by the current account, and have a status of `active`. The asset group must also remain available. | Asset type | New protocol `input_references[].type` | Compatibility protocol nested field | | ---------- | -------------------------------------- | ----------------------------------- | | `image` | `image_url` | `image_url.url` | | `video` | `video_url` | `video_url.url` | | `audio` | `audio_url` | `audio_url.url` | The reference type must match the `asset_type` specified when creating the asset. `asset://` is used in video reference fields and cannot be used as a browser download URL.

New Video Protocol

First check the current model Schema by endpoint path: ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \ | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema' ``` Submit the request after confirming that the model supports reference images. The following uses the Seedance 2.5 parameters successfully verified in production during this test: `duration=4`, `resolution="480p"`, `aspect_ratio="3:4"`, and `generate_audio=false`. The new protocol uses `input_references[].url` directly, where `ASSET_ID` is the asset ID previously returned by AIHubMix: ```bash theme={null} 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 ``` The new protocol uses an integer `duration` for the requested duration; other allowed values are defined by the model Schema. `resolution="480p"` specifies the requested resolution tier and does not guarantee that the output width or height is exactly 480 pixels. Refer to the generated file for its actual dimensions. First and last frames can use `frame_images[].image_url.url` together with `frame_type`, only when the model supports the corresponding capability. See [Video Generation](/en/api/aihubmix-video-generation) for the full parameters.

Compatibility Video Protocol

For existing clients using `/v1/videos`, place references in `content` or `extra_body.content`, with each URL nested inside the corresponding media object. This example uses `extra_body.content`: The compatibility example retains `doubao-seedance-2-0-260128` and is based on the existing compatibility API contract and the official BytePlus asset reference documentation. Seedance 2.0 video generation and creation through the `/v1/videos` compatibility API were not tested in this verification. The results for Seedance 2.5 with the new protocol cannot be directly applied to this example. ```bash theme={null} 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 . ``` Run only one of the two examples. Each video creation is a separate request. Do not include `input_references` in a compatibility request. If `content` is provided in both locations, `extra_body.content` overrides the top-level `content`; providing it in only one location is recommended. Use the `id` returned by the compatibility API with `GET /v1/videos/{id}` to query status, then download through `GET /v1/videos/{id}/content` after completion. Do not query `/ai/v1/videos` with a compatibility API ID. See the [Compatibility Video API](/en/api/Video-Gen) for details.

7. Poll and Download the New-Protocol Video

The following Python example continues only from the new-protocol creation steps above. It reads `VIDEO_ID` from the environment and does not create another task. The `requests` package must be installed. ```python theme={null} 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") ``` The 30-minute limit is the example's local waiting limit, not a server-side task timeout. An HTTP `200` query response does not mean generation succeeded; you must check `status`. Use `/ai/v1/videos/{id}` for polling. The unified task endpoint `/ai/v1/tasks/{id}` provides a read-only snapshot. Query and download videos using the same API Key used to create the task. Download promptly after completion and retain your own copy. Results have a retention period defined by `expires_at`, and expired results may return `410 artifact_expired`.

Workflow Verification

The production verification on 2026-09-07 used a publicly accessible direct HTTPS JPEG URL, web verification completed personally by the person depicted, and the Seedance 2.5 parameters above. The following results were observed: | Step | Result in this verification | | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Create an asset group | HTTP `201`, `status=pending_auth` | | Create a verification session | HTTP `201`, `status=pending` | | Query after personal verification | Session HTTP `200`, `status=verified`; asset group `active` | | Create and query an image asset | Creation HTTP `201`, `status=processing`; subsequent query HTTP `200`, `status=active` | | Create and query a new-protocol video | Creation HTTP `200`, `status=in_progress`; subsequent query HTTP `200`, `status=completed`, `error=null` | | Download the video | HTTP `200`, `Content-Type: video/mp4`; the file was fully decoded with ffmpeg | The file was 1,558,358 bytes. ffprobe reported H.264, 24 fps, 560 × 752 pixels, 4.041667 seconds, and no audio track. These values describe this particular generation result and do not mean that every request produces the same dimensions, duration, or file size. The verification page initially displayed `internal error`; a subsequent API query still showed `pending`, and the cause of the page error has not been confirmed. The test then used a new page for a separate test group. After the person completed the steps personally, the session was confirmed as `verified` and the asset group as `active`. Using a new group was specific to this test and is not a general recommendation to repeatedly recreate asset groups, nor does it mean that the original session had ended. This verification did not test Seedance 2.0 video generation, creation through the compatibility API, audio or video assets, first and last frames, deletion, or other combinations of exceptional conditions. The corresponding descriptions remain based on the API contract and official documentation. This verification does not cover every scenario in the guide.

Idempotent Retries

* If asset creation times out or the response is lost, retain the original `Idempotency-Key`, `client_reference_id`, URL, and `asset_type`, and resend the same request. If either identifier matches an existing asset in the same account and asset group, that asset is reused. * If the URL or `asset_type` associated with the same identifier changes, the response is `409 asset_idempotency_conflict`. Updating a signed image URL also counts as a URL change. * If neither identifier is provided, deduplication across requests is not guaranteed. Use a new identifier only when you intend to create another asset. * Once you have an asset ID, prefer querying with `GET /ai/v1/assets/{id}`. `reconciling` does not mean failure and should not prompt creation with a new identifier. * After asset deletion is complete, the original idempotency identifiers are no longer retained. Do not rely on them to recover a deleted asset or replay an old creation request. * The idempotency contract in this section applies only to asset creation. It does not apply to asset group, verification session, or video creation. If a new-protocol video creation response is lost, first use `GET /ai/v1/videos?limit=20&order=desc` to find the original task and avoid duplicate generation.

Delete Assets and Asset Groups

Before deletion, confirm that all videos referencing the asset have finished, including tasks submitted through the compatibility API. Deletion cannot be undone. Manage any downloaded video files yourself. Delete a single asset: ```bash theme={null} curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` A `202` response means deletion is still in progress. Continue querying with `GET /ai/v1/assets/{id}` until `status=deleted`. Repeated deletion requests return the current status. If it is `reconciling`, continue checking the result and contact support if the process remains incomplete. Deleting an entire asset group also deletes its assets and requires explicitly passing `cascade=true`: ```bash theme={null} curl --fail-with-body -sS -X DELETE \ "$BASE_URL/ai/v1/asset-groups/$GROUP_ID?cascade=true" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` An accepted request returns `202`. Query with `GET /ai/v1/asset-groups/{id}`. `deleting` means deletion is in progress, `partially_deleted` means deletion is not yet complete, and only `deleted` indicates completion. Lists exclude deleted asset groups by default. `409 asset_group_in_use` means that operations or video tasks are still unfinished. Wait, query the relevant statuses, and retry. You must confirm that compatibility video tasks have finished yourself; do not rely on deletion requests to automatically determine whether all compatibility tasks are still using the group.

FAQ

Why Can I Still Not Add Assets After Completing the Web Steps?

First query the verification session and asset group, and use `verified` and `active` as the criteria. Perform the same checks if the page displays `internal error`. Do not repeatedly create sessions for the same group while the session is `pending`. Query again later if the result has not been confirmed. If the process remains incomplete, contact support with the IDs; you do not need to provide the verification link or the person's photo.

Why Does Video Generation Still Fail When the Asset Is Available?

Check that the reference uses the asset ID returned by AIHubMix, all assets belong to the same group, the media types match, and the current model supports the corresponding inputs. An asset status of `active` means the asset is available. You must still check the video task's completion status and error information separately.

How Do I Handle Common API Errors?

| HTTP | `error.code` | Action | | ---- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | 400 | `invalid_request` | Check the request fields, structure, and video protocol used | | 400 | `asset_group_invalid` | Check the asset group name | | 400 | `asset_invalid` | Check the URL, asset type, and request identifiers | | 400 | `asset_binding_mismatch` | Reference assets from only one asset group in each video request | | 400 | `cascade_confirmation_required` | Pass `cascade=true` after confirming your intent to delete the entire group | | 401 | `authentication_failed` | Check the API Key environment variable and authentication header | | 403 | `async_not_enabled` | Enable async tasks before using the new video API | | 404 | `asset_group_not_found`, `asset_not_found`, `verification_session_not_found` | Check the resource ID and owning account | | 409 | `asset_group_not_verified` | Query the personal verification result and wait for the asset group to become available | | 409 | `verification_session_active` | Query the existing session or asset group to avoid duplicate attempts | | 409 | `asset_not_ready` | Query the asset status and wait for `active` before generating a video | | 409 | `asset_idempotency_conflict` | Check the original URL and type associated with the identifier | | 409 | `asset_group_in_use` | Wait for related operations and video tasks to finish before deletion | | 503 | `asset_group_unavailable`, `verification_unavailable`, `asset_unavailable` | Retry later; contact support if it remains unavailable | For other video errors, see [Async Task Error Codes](/en/api/async-tasks#error-codes). When submitting feedback, include the time of the occurrence, HTTP status, `error.code`, the returned `error.tid` (if any), and related resource IDs. Do not provide your API Key, verification link, or signed image URL.

References

* [BytePlus: Add Real-Person Assets](https://docs.byteplus.com/en/docs/ModelArk/2315856) * [BytePlus: Generate Portrait Videos with Seedance](https://docs.byteplus.com/en/docs/ModelArk/2608626) * [AIHubMix Native Video Generation](/en/api/aihubmix-video-generation) * [OpenAI-Compatible Video API](/en/api/Video-Gen) * [Async Tasks](/en/api/async-tasks) Last updated: 2026-09-07