> ## 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 для генерации видео с цифровыми персонажами Dreamina

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

Генерация видео с цифровыми персонажами на основе аудио (OmniHuman 1.5). Предоставьте фотографию персонажа и аудио, чтобы сгенерировать видео, в котором персонаж говорит с синхронизацией губ.

### Заголовки запроса

| Заголовок | Значение |
| - | - |
| `Authorization` | `Bearer <ваш API ключ>` |
| `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, должно быть доступно по публичному URL. Рекомендуемая продолжительность — до 60 секунд (1080p рекомендуется ≤30 секунд, 720p ≤60 секунд).
* `image_url` и `audio_url` должны быть доступны по публичному 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.