Doubao Private Virtual Portrait Assets

Private virtual portrait assets let you reference a virtual character in video generation without personal verification. This guide covers asset group creation, image upload, status checks, and video generation. Public virtual portrait catalogs are outside this guide.

Prerequisites

Set AIHUBMIX_API_KEY in the environment.
Enable the target video model and virtual portrait asset capability for your account.
Prepare a public HTTPS image URL that the model provider can fetch.

Create a group

Send kind: "virtual_portrait" to POST /ai/v1/asset-groups. A successful request returns 201; the group normally becomes active with authorization status not_required.

BASE_URL="https://aihubmix.com"
curl --fail-with-body -sS -X POST "$BASE_URL/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My virtual portrait","kind":"virtual_portrait"}' | jq

Virtual portrait groups do not use verification sessions. Save the returned group ID and use it in the next request.

Upload and wait for an image

curl --fail-with-body -sS -X POST "$BASE_URL/ai/v1/asset-groups/<group_id>/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/virtual-portrait.jpg","asset_type":"image","client_reference_id":"portrait-001"}' | jq

The response normally starts with status=processing. Query GET /ai/v1/assets/<asset_id> until the status is active. Do not use an asset while it is creating, processing, or reconciling. Use a public URL without login, private-network access, Base64 data, or embedded credentials. Images should be smaller than 30 MB, between 300 and 6000 pixels in both dimensions, and have an aspect ratio between 0.4 and 2.5.

Generate a video

Use the AIHubMix asset ID as asset://<asset_id>:

curl --fail-with-body -sS -X POST "$BASE_URL/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2-5-260628","prompt":"Make the virtual portrait smile naturally and turn slightly toward the camera.","input_references":[{"type":"image_url","url":"asset://<asset_id>"}]}' | jq

Query GET /ai/v1/videos/<video_id> until status=completed. Treat in_progress as pending and stop on failed or cancelled. Retrieve the completed video with GET /ai/v1/videos/<video_id>/content. Existing /v1/videos clients can place the reference in extra_body.content and retrieve content from /v1/videos/<id>/content.

Errors and deletion

asset_not_ready means that the asset is not active yet. asset_binding_mismatch means that the request references incompatible private assets. channel_pin_conflict means that an explicit channel does not match the asset binding. An unavailable channel returns channel_unavailable. When a virtual group is creating or reconciling, its creation result is unknown. The service keeps the local record and recovery locator and does not automatically delete it. Keep API keys in environment variables and never include them in logs or support requests.

Getting Started

Gateway Features

Model Capabilities

Protocol Reference

Platform Management

Doubao Private Virtual Portrait Assets

Prerequisites

Create a group

Upload and wait for an image

Generate a video

Errors and deletion

​Prerequisites

​Create a group

​Upload and wait for an image

​Generate a video

​Errors and deletion

Prerequisites

Create a group

Upload and wait for an image

Generate a video

Errors and deletion