> ## 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` によってタスクの状態と最終動画のアドレスをポーリングできます。**このインターフェースは無料です。**

## 申請プロセス

Dreamina シリーズ API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API トークンを取得し、保管してください。

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。

**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で一般残高をチャージできます。

## リクエストパラメータ

**リクエストヘッダー**

* `accept`：JSON形式のレスポンス結果を受け取ることを指定し、`application/json` を記入します。
* `authorization`：APIを呼び出すためのキーで、形式は `Bearer {token}` です。
* `content-type`：`application/json` を記入します。

**リクエストボディ**

| パラメータ | タイプ | 必須 | 説明 |
| - | - | - | - |
| `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.