> ## 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, сначала получите ваш API Token в [консоли Ace Data Cloud](https://platform.acedata.cloud/console/applications) для резервного копирования.

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

**Один 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",
  "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` — это массив деталей пакетных задач (каждый элемент имеет такой же формат, как и результат одиночного запроса), `count` — количество задач, возвращенных в этот раз.

## Обработка ошибок

При вызове 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.