> ## 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 整合指南 - Ace Data Cloud

## 即夢數字人視頻生成 API

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

音頻驅動的數字人口播視頻生成（OmniHuman 1.5）。提供一張人物照片和一段驅動音頻，生成人物開口說話、口型同步的視頻。

### 請求頭

| 頭 | 值 |
| - | - |
| `Authorization` | `Bearer <你的 API Key>` |
| `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\[] | 否 | 主體 mask URL，用於多人圖中指定驅動對象 |
| `callback_url` | string | 否 | 傳入則立即返回 `task_id`，結果生成後回調該地址 |
| `async` | boolean | 否 | 設為 `true` 時立即返回 `task_id`，無需 `callback_url`，通過 `/dreamina/tasks` 輪詢結果 |

### 輸入建議

* **圖片**：清晰、光線良好的正面人像效果最佳；人臉无遮挡、在畫面中占比適中。
* **音頻**：mp3/wav，需公網可達。建議時長控制在 60 秒以內（1080p 建議 ≤30 秒，720p ≤60 秒）。
* `image_url` 與 `audio_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.