---

name: dreamina-video description: Generate talking-photo digital human videos with Dreamina (ByteDance OmniHuman) via AceDataCloud API. Use when animating a portrait image with a driving audio track to produce a lip-synced video where the person speaks. Supports mask-based multi-person targeting and async task polling. license: Apache-2.0 metadata: author: acedatacloud version: "1.0" compatibility: Requires ACEDATACLOUD_API_TOKEN in .env file (see _shared/authentication.md).

Dreamina Talking-Photo Video Generation

Generate audio-driven digital human videos through AceDataCloud's Dreamina API (powered by ByteDance OmniHuman 1.5). Provide a portrait image and driving audio to produce a lip-synced talking-photo video.

Setup: See authentication for token setup.

Quick Start

curl -X POST https://api.acedata.cloud/dreamina/videos \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/portrait.jpg",
    "audio_url": "https://example.com/voiceover.mp3",
    "async": true
  }'

The response contains a task_id. Poll for the result:

curl -X POST https://api.acedata.cloud/dreamina/tasks \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"action": "retrieve", "id": "<task_id>"}'

Async: See async task polling. Poll POST /dreamina/tasks until response.data.status equals "done".

Model

Model	Description
omnihuman-1.5	ByteDance OmniHuman 1.5 — audio-driven lip-sync digital human (default and only available model)

Workflow

Basic Talking-Photo

Generate a video where a portrait person speaks a given audio track.

POST /dreamina/videos
{
  "model": "omnihuman-1.5",
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/speech.mp3",
  "prompt": "Natural expression, steady head movement, warm tone",
  "async": true
}

Multi-Person Mask

To target a specific person in a group image, provide mask_url array with subject mask URLs.

POST /dreamina/videos
{
  "image_url": "https://example.com/group-photo.jpg",
  "audio_url": "https://example.com/speech.wav",
  "mask_url": ["https://example.com/person-mask.png"],
  "async": true
}

Parameters

Parameter	Required	Values	Description
image_url	✓	URL	Portrait image URL (public, clear frontal face works best)
audio_url	✓	URL	Driving audio URL (mp3/wav, publicly reachable, keep under 60s)
model		"omnihuman-1.5"	Model to use (default: omnihuman-1.5)
prompt		string	Steers expression, emotion, stability, and style
mask_url		array of URLs	Subject mask URLs to target a specific person in a multi-person image
callback_url		URL	Webhook for result delivery
async		boolean	Return task ID immediately for polling

Task Queries

Retrieve one task:

POST /dreamina/tasks
{"action": "retrieve", "id": "<task_id>"}

You can also query by trace_id:

POST /dreamina/tasks
{"action": "retrieve", "trace_id": "<trace_id>"}

Retrieve several tasks:

POST /dreamina/tasks
{"action": "retrieve_batch", "ids": ["<id1>", "<id2>"]}

A completed response contains response.data.video_url when response.data.status is "done".

Gotchas

• Both image_url and audio_url are required
• The portrait should be a clear, well-lit, front-facing image with the face unobstructed
• Audio must be publicly reachable; keep it under 60s (≤30s recommended for 1080p quality)
• Use async: true or callback_url for longer jobs — synchronous mode may time out
• mask_url is only needed for multi-person images when you want to target one specific person
• Check response.data.status when polling — the terminal state is "done"
• Billed by output video duration

MCP: See MCP servers for tool-use integration.