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

> Dreamina API guide - Ace Data Cloud

## Інтеграція та використання Dreamina Tasks API

Dreamina Tasks API використовується для запиту результатів виконання завдань з відео цифрових людей, створених за допомогою [Dreamina Video Generation API](https://platform.acedata.cloud/documents/dreamina-videos-integration). Коли ви передаєте `callback_url` або `async: true` в інтерфейсі генерації, інтерфейс негайно повертає `task_id`, за яким ви можете опитувати статус завдання та остаточну адресу відео через цей інтерфейс за `task_id` або `trace_id`. **Цей інтерфейс безкоштовний.**

## Процес подачі заявки

Щоб використовувати серію API Dreamina, спочатку перейдіть до [консолі Ace Data Cloud](https://platform.acedata.cloud/console/applications) для отримання вашого API Token, зберігайте його на випадок потреби.

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, щоб запросити реєстрацію та вхід, після чого ви будете автоматично повернені на цю сторінку.

**Один API Token дозволяє викликати всі послуги платформи, не потрібно окремо подавати заявку на кожну послугу.** Перший запит на отримання токена надає безкоштовний ліміт, щоб ви могли безкоштовно спробувати; якщо ліміт вичерпано, ви можете поповнити загальний баланс в [консолі](https://platform.acedata.cloud/console/coin).

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

**Request Headers**

* `accept`：вказує на прийняття відповіді у форматі JSON, заповніть `application/json`.
* `authorization`：ключ для виклику API, формат `Bearer {token}`.
* `content-type`：заповніть `application/json`.

**Request Body**

| Параметр | Тип | Обов'язковий | Опис |
| - | - | - | - |
| `action` | string | Ні | Тип операції, `retrieve` (за замовчуванням, запит одного) або `retrieve_batch` (пакетний запит) |
| `id` | string | Ні | ID завдання для запиту (повертається при створенні відео `task_id`) |
| `trace_id` | string | Ні | ID відстеження завдання для запиту, може бути використаний замість `id` |
| `ids` | string\[] | Ні | Список ID завдань для пакетного запиту, використовується разом з `retrieve_batch` |

> При запиті одного завдання, `id` та `trace_id` повинні бути надані хоча б один.

## Запит одного завдання

### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve",
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}'
```

### Python

```python theme={null}
import requests

url = "https://api.acedata.cloud/dreamina/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "retrieve",
    "id": "362b4fed-67bd-11f1-ad11-00163e57d510"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

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

Після успішного запиту API повертає деталі цього завдання. `request` - це тіло запиту, яке було надіслано під час створення завдання, `response` - це тіло відповіді після завершення завдання, де `data.video_url` є адресою згенерованого відео цифрової людини:

```json theme={null}
{
  "id": "362b4fed-67bd-11f1-ad11-00163e57d510",
  "started_at": 1769262721.823,
  "finished_at": 1769262769.123,
  "elapsed": 47.3,
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "request": {
    "model": "omnihuman-1.5",
    "image_url": "https://cdn.acedata.cloud/4hfydw.jpg",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  },
  "response": {
    "success": true,
    "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"
    }
  }
}
```

Опис полів:

* `id`：унікальний ID завдання на створення відео.
* `trace_id`：ID відстеження цього запиту, використовується для усунення проблем.
* `request`：вміст запиту, надісланого під час створення завдання.
* `response`：вміст відповіді, повернутого після завершення завдання. Коли `response.data.status` є `done`, `response.data.video_url` є остаточною адресою відео.
* `created_at`：час створення завдання, Unix-час (секунди, з плаваючою комою).
* `started_at`：час початку виконання завдання, Unix-час (секунди, з плаваючою комою).
* `finished_at`：час завершення завдання, Unix-час (секунди, з плаваючою комою). Поле не повертається, якщо завдання не завершено.
* `elapsed`：час виконання завдання, одиниця виміру - секунди (з плаваючою комою, зберігається 3 знаки після коми). Поле не повертається, якщо завдання не завершено.

> Якщо завдання ще не завершено, `status` може бути не в стані `done`; якщо завдання не існує або результати ще не згенеровані, інтерфейс поверне порожній об'єкт `{}`, будь ласка, спробуйте пізніше.

## Пакетний запит завдань

Встановіть `action` на `retrieve_batch` і передайте масив `ids`:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/dreamina/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "ids": [
    "362b4fed-67bd-11f1-ad11-00163e57d510",
    "0c0b4d3a-2f1e-4a6b-9c2d-2b3c4d5e6f70"
  ]
}'
```

У повернутому результаті `items` є масивом деталей пакетних завдань (кожен елемент має такий же формат, як і результат запиту одного).

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

При виклику API, якщо виникає помилка, повертається відповідний код помилки та інформація:

* `400 bad_request`：помилка запиту, можливо, відсутні необхідні параметри `id` / `trace_id` тощо.
* `401 invalid_token`：неавторизовано, токен авторизації недійсний або відсутній.
* `429 too_many_requests`：занадто багато запитів, перевищено ліміт швидкості.
* `500 api_error`：внутрішня помилка сервера.

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

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "id or trace_id is required to retrieve a task"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Висновок

Завдяки цьому документу ви дізналися, як використовувати Dreamina Tasks API для запиту результатів окремих або пакетних завдань з відео цифрових людей. У поєднанні з `callback_url` / `async` асинхронним режимом інтерфейсу генерації, ви можете реалізувати стабільне опитування. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.


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