Dreamina Video

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

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

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.