> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Dreamina Videos

> Dreamina API guide - Ace Data Cloud

## Dreamina Digital Human Video Generation API

`POST https://api.acedata.cloud/dreamina/videos`

Audio-driven digital human lip-sync video generation (OmniHuman 1.5). Provide a photo of a person and a piece of driving audio to generate a video of the person speaking with synchronized lip movements.

### Request Headers

| Header | Value |
| - | - |
| `Authorization` | `Bearer <dein API Key>` |
| `Content-Type` | `application/json` |

### Request Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | No | Model, default `omnihuman-1.5` |
| `image_url` | string | Yes | Public URL of the person's photo, clear frontal view is recommended |
| `audio_url` | string | Yes | Public URL of the driving audio (mp3/wav), recommended \< 60 seconds |
| `prompt` | string | No | Control expression, emotion, stability, and style |
| `mask_url` | string\[] | No | Subject mask URL, used to specify the driving object in a group image |
| `callback_url` | string | No | If provided, immediately returns `task_id`, callback to this address after result generation |
| `async` | boolean | No | Set to `true` to immediately return `task_id`, no need for `callback_url`, poll results via `/dreamina/tasks` |

### Input Recommendations

* **Image**: Clear, well-lit frontal portrait works best; face unobstructed, occupying a moderate proportion of the frame.
* **Audio**: mp3/wav, must be publicly accessible. Recommended duration is within 60 seconds (1080p recommended ≤30 seconds, 720p ≤60 seconds).
* Both `image_url` and `audio_url` must be publicly accessible.

### Response Example

```json theme={null}
{
  "success": true,
  "task_id": "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": {
    "task_id": "362b4fed67bd11f1ad1100163e57d510",
    "status": "done",
    "video_url": "https://cdn.acedata.cloud/634d760216.mp4",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  }
}
```

### Asynchronous and Querying

The interface defaults to synchronous return of the final video. For longer tasks, you can use one of two asynchronous modes:

* Provide `callback_url`: The interface immediately returns `task_id`, and the result is sent to this address after generation.
* Provide `async: true`: The interface immediately returns `task_id`, then poll results via `POST /dreamina/tasks` (free) by `task_id` or `trace_id`.

For polling contracts, see [Dreamina Tasks API](https://platform.acedata.cloud/documents/dreamina-tasks-integration).

### Error Handling

| Status Code | Code | Meaning |
| - | - | - |
| 400 | `bad_request` | Missing or invalid parameters (e.g., `image_url` / `audio_url`) |
| 401 | `authorization_missing` / `invalid_token` | Authorization token missing or invalid |
| 403 | `forbidden` | Insufficient balance/quota, or upstream unauthorized |
| 429 | `too_many_requests` | Too many requests, exceeded rate limit |
| 500 | `api_error` | Internal server error |

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "image_url is required (a public URL of a portrait image)"
  },
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

### Billing

Charged based on the duration of the generated video, maximum package approximately **¥1/second** (e.g., a 10-second video costs about ¥10).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.