How to Use a Real Face in Seedance 2.5 with AIHubMix Real-Human Assets

AI video becomes much more useful when the person on screen stays recognizable from one scene to the next. AIHubMix real-human assets provide a consent-based way to use an approved face in Seedance video generation while keeping authorization, asset processing, and generation as separate, verifiable steps.

This guide explains what real-human video is, how the AIHubMix workflow works, why it is useful, and how to create a Seedance 2.5 video from a real face. It also explains the difference between the native Seedance 2.5 API and compatible Seedance 2.0 integrations.

What Is Real-Human Video?

Real-human video is AI-generated video that uses an authorized person as an identity reference. The model can change the setting, clothing, action, camera movement, voice, or language while preserving the person’s recognizable appearance.

This is different from ordinary text-to-video generation. A text prompt describes what should happen, but it does not reliably identify a specific real person. A real-human asset gives the model an approved visual reference that can be reused across multiple videos.

Typical applications include creator avatars, virtual presenters, product explainers, localized campaigns, training videos, brand characters, and short-form social content.

How the AIHubMix Workflow Works

The workflow has five main stages:

1. Create an asset group for one person.
2. Ask the person in the image to complete the authorization flow.
3. Add a portrait and wait until the asset is active.
4. Reference the active asset with an asset:// URI.
5. Submit a Seedance video task and poll it until completion.

The separation is deliberate. Authorization happens before generation, asset readiness can be checked independently, and every important stage exposes a status that your application can monitor.

Why Use AIHubMix?

One API for the complete workflow

AIHubMix provides endpoints for asset groups, verification sessions, human assets, and asynchronous video generation. The same account and API key can manage the full pipeline.

Explicit authorization

The person in the portrait completes the authorization page. This creates a clear consent step before the image is used as a reusable real-human reference.

Reusable identity assets

After an image becomes active, applications can reuse its asset ID across multiple video requests instead of uploading the original image every time.

Seedance-ready generation

The native Seedance 2.5 endpoint supports text, image, video, and audio references, plus controls for duration, resolution, aspect ratio, and audio generation.

Observable, production-friendly states

Your application can wait for verified, active, and completed rather than guessing whether an operation finished. This makes retries and error handling easier to implement.

Step-by-Step Tutorial

Step 1: Prepare an API key and portrait

Create an API key in the AIHubMix Console. Keep it private. In Terminal, set it as an environment variable:

export AIHUBMIX_API_KEY="your_api_key"

Prepare a direct HTTPS image URL. The URL must return the image file without login or custom headers and must remain available while AIHubMix processes it.

Recommended image requirements:

• JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, or HEIF
• Less than 30 MB
• Width and height greater than 300 pixels and less than 6000 pixels
• Aspect ratio greater than 0.4 and less than 2.5
• A clear portrait of the same person who completes authorization

Step 2: Create a real-human asset group

Run this command in Terminal:

curl -sS -X POST "https://aihubmix.com/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My real-human asset"}'

Save the returned id, which looks like ag_...:

GROUP_ID="ag_your_group_id"

A new group normally starts with pending_auth.

Step 3: Create an authorization session

Use the group ID to request a verification session:

curl -sS -X POST \
  "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

The response contains a temporary verification_url. Open that URL in a browser and ask the person in the portrait to review the purpose and complete the authorization flow.

The URL is sensitive and temporary. Do not publish it, commit it to a repository, or include it in screenshots.

Step 4: Verify authorization and group status

After the person finishes the browser flow, query both resources:

curl -sS "https://aihubmix.com/ai/v1/verification-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

curl -sS "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Continue only when the verification session is verified and the asset group is active. A browser error page does not determine the final result; use the API status.

Step 5: Add the portrait

Submit the direct image URL:

curl -sS -X POST \
  "https://aihubmix.com/ai/v1/asset-groups/$GROUP_ID/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: portrait-001" \
  -d '{
    "url":"https://cdn.example.com/portrait.jpg",
    "asset_type":"image",
    "client_reference_id":"portrait-001"
  }'

Save the returned asset ID and poll it:

ASSET_ID="ast_your_asset_id"
curl -sS "https://aihubmix.com/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

Use the asset only when its status is active. creating and processing mean that it is not ready yet.

Step 6: Generate a Seedance 2.5 video

The real-human asset belongs in input_references[].url. It should not be pasted into the prompt text:

curl -sS -X POST "https://aihubmix.com/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\":\"doubao-seedance-2-5-260628\",
    \"prompt\":\"A realistic vertical vlog. The person smiles, waves, and says in Japanese: やっほー！今日も笑顔でね！ Keep the face consistent, synchronize lip movement, use natural hand motion, and add no subtitles.\",
    \"duration\":5,
    \"resolution\":\"720p\",
    \"aspect_ratio\":\"3:4\",
    \"generate_audio\":true,
    \"input_references\":[{\"type\":\"image_url\",\"url\":\"asset://$ASSET_ID\"}]
  }"

The response returns a video task ID. Poll GET /ai/v1/videos/{id} until the task is completed, then download the output promptly because video URLs are temporary.

Seedance 2.5 and Seedance 2.0

Seedance 2.5 uses the native /ai/v1/videos endpoint described above. Older integrations may use Seedance 2.0 with the compatible /v1/videos protocol and a different content structure.

Do not mix the two request formats. Before production use, check the live model schema for supported durations, resolutions, reference types, audio behavior, and endpoint paths.

Prompting Best Practices

Describe the environment, action, timing, camera movement, voice, and constraints. A strong prompt might specify a kimono, falling cherry blossoms, a gentle wave, Japanese dialogue, synchronized lip movement, natural hair motion, and no subtitles.

Five seconds works well for a short greeting. If the video includes several actions or a long sentence, use a longer duration or shorten the script so the performance does not feel rushed.

Use one identity reference for a simple test. Add additional references only when the model schema supports them and each asset belongs to the same asset group.

Common Problems

• The group is not active: wait for the verification session to become verified and the group to become active.
• The asset is processing: poll the original asset ID; do not create duplicates with a new ID.
• The image URL fails: use a public HTTPS file URL, not a local path, login page, or share page.
• The video rejects the asset: confirm that the asset is active, belongs to the same account, and uses the correct media type.
• Playground does not show asset://: Playground image upload and real-human asset registration are separate workflows. Use the API reference field for registered assets.

Final Checklist

1. API key configured securely.
2. Asset group created.
3. Person authorization completed.
4. Group status is active.
5. Portrait asset status is active.
6. Video request uses asset://<asset_id>.
7. Video task is polled until completed.

AIHubMix real-human assets give developers a practical way to build consent-based, identity-consistent video experiences with Seedance. Start with one approved portrait and a short test clip, then expand the same workflow into creator tools, brand content, and production applications.