> ## 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 API guide - 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\[] | 否 | 主体マスク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"
  }
}
```

### 非同期とクエリ

インターフェースはデフォルトで最終動画を同期的に返します。長いタスクの場合、次の2つの非同期モードのいずれかを使用できます：

* `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) を参照してください。

### エラーハンドリング

| ステータスコード | コード | 意味 |
| - | - | - |
| 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.