> ## 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",
  "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.