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.

dreamina-video