> ## 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

## API для генерації відео з цифровими персонажами

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

Генерація відео з цифровими персонажами на основі аудіо (OmniHuman 1.5). Надати фотографію персонажа та аудіо, щоб згенерувати відео, де персонаж говорить з синхронізацією губ.

### Заголовки запиту

| Заголовок | Значення |
| - | - |
| `Authorization` | `Bearer <ваш API Key>` |
| `Content-Type` | `application/json` |

### Параметри запиту

| Параметр | Тип | Обов'язковий | Опис |
| - | - | - | - |
| `model` | string | Ні | Модель, за замовчуванням `omnihuman-1.5` |
| `image_url` | string | Так | Публічний URL фотографії персонажа, рекомендується чітке зображення обличчя |
| `audio_url` | string | Так | Публічний URL аудіо (mp3/wav), рекомендується \< 60 секунд |
| `prompt` | string | Ні | Контроль виразу обличчя, емоцій, стабільності та стилю |
| `mask_url` | string\[] | Ні | URL маски для основного об'єкта, щоб вказати об'єкт для кількох персонажів |
| `callback_url` | string | Ні | Якщо передано, відразу повертає `task_id`, результати генеруються та повертаються на цю адресу |
| `async` | boolean | Ні | Якщо встановлено в `true`, відразу повертає `task_id`, без `callback_url`, через `/dreamina/tasks` опитує результати |

### Рекомендації щодо введення

* **Зображення**: Чітке, добре освітлене зображення обличчя є найкращим; обличчя не повинно бути закритим, займати помірну частину кадру.
* **Аудіо**: mp3/wav, має бути доступним з публічної мережі. Рекомендується тривалість до 60 секунд (1080p рекомендується ≤30 секунд, 720p ≤60 секунд).
* `image_url` та `audio_url` повинні бути доступні з публічної мережі.

### Приклад відповіді

```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"
  }
}
```

### Асинхронний режим та запит

Інтерфейс за замовчуванням синхронно повертає фінальне відео. Для тривалих завдань можна використовувати один з двох асинхронних режимів:

* Передати `callback_url`: інтерфейс відразу повертає `task_id`, результати генеруються та повертаються на цю адресу.
* Передати `async: true`: інтерфейс відразу повертає `task_id`, потім через `POST /dreamina/tasks` (безкоштовно) опитує результати за `task_id` або `trace_id`.

Деталі опитування див. у [Dreamina Tasks API](https://platform.acedata.cloud/documents/dreamina-tasks-integration).

### Обробка помилок

| Код статусу | code | Значення |
| - | - | - |
| 400 | `bad_request` | Відсутні або недійсні параметри (наприклад, `image_url` / `audio_url`) |
| 401 | `authorization_missing` / `invalid_token` | Відсутній або недійсний токен авторизації |
| 403 | `forbidden` | Недостатньо коштів/лімітів або несанкціоновано з боку постачальника |
| 429 | `too_many_requests` | Занадто багато запитів, перевищено ліміт швидкості |
| 500 | `api_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"
}
```

### Оплата

Оплата за тривалість згенерованого відео, максимальний тариф приблизно **¥1/сек** (наприклад, 10-секундне відео приблизно ¥10).


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