> ## 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 集成指南 - 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` 轮询任务状态与最终视频地址。**本接口免费。**

## 申请流程

要使用 Dreamina 系列 API，首先到 [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` 为批量任务详情数组（每个元素与单个查询结果格式一致），`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.