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

# Maestro タスク照会 API 連携ガイド

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro タスク照会 API の主な機能は、[Maestro 動画生成 API](/ja/guides/maestro/maestro_videos)（`POST /maestro/videos`）から返されるタスク ID を通じて、そのタスクの実行状態と最終結果を照会することです。

本ドキュメントでは、Maestro タスク照会 API の連携ガイドについて詳しく説明します。動画生成は非同期タスクであるため、送信後は本インターフェースを使用して進捗と完成動画をポーリングで取得する必要があります。**ポーリングは無料で、クレジットを消費しません。**

`POST https://api.acedata.cloud/maestro/tasks`

## 申請手順

Maestro タスク照会 API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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

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

> 📘 完全なドキュメント：[Maestro タスク照会 API →](https://platform.acedata.cloud/documents/maestro-tasks)

## 単一タスクの照会

動画タスクの作成方法については、ドキュメント [Maestro 動画生成 API](/ja/guides/maestro/maestro_videos) を参照してください。ここでは、その返り値のタスク ID の例である `f57e99c4f60f4373a15517742ce2357d` を用いて、その状態と結果を照会する方法を説明します。

### リクエストヘッダーとリクエストボディの設定

**Request Headers** には以下が含まれます。

* `accept`：JSON 形式のレスポンス結果を受け取るよう指定します。ここでは `application/json` を設定します。
* `authorization`：API を呼び出すためのキーです。申請後、直接ドロップダウンから選択できます。
* `content-type`：リクエストボディの形式です。ここでは `application/json` を設定します。

**Request Body** には以下が含まれます。

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| `id` | string | 単一タスク照会時は必須 | `POST /maestro/videos` が返す `task_id` |
| `action` | string | いいえ | `retrieve`（デフォルト、単一タスクを照会）；履歴リストを照会する場合は `retrieve_batch` に固定 |

### コード例

対応する CURL コードは以下のとおりです。

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'
```

対応する Python コードは以下のとおりです。

```python theme={null}
import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

### レスポンス例

リクエストが成功すると、API はこの動画タスクの状態と結果を返します。タスク完了時の返却例は以下のとおりです（各言語は 1 つの `variant` に対応します）。

```json theme={null}
{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}
```

返却結果のフィールド説明は以下のとおりです。

* `id`：この動画タスクの ID であり、今回の動画生成タスクを一意に識別するために使用されます。
* `status`：タスクの状態です。値は `pending → planning → producing → succeeded`（または `failed`）です。タスクが完了しているかどうかは、このトップレベルの `status` を基準とします。
* `elapsed`：タスクの経過時間（秒）。
* `progress`：トップレベルの進捗オブジェクトです。`percent`（0～100）はタスク成功後に 100 に補正されます。`stage` と `message` は AI ディレクターの直近の進捗イベントを反映します（そのため成功後も `stage` は `producing` などの最後の実行段階のままである可能性があります）。進捗バーの表示に直接使用できます。
* `request`：タスク開始時のリクエストボディ。
* `response`：タスクの返却情報。
  * `success`：タスクが成功したかどうか。
  * `data.variants`：各言語に対応する完成動画オブジェクトであり、`lang`、`aspect`、`title`、`output_url`（完成動画のダウンロード URL）などを含みます。
  * `data.project`：プロジェクト全体の成果物であり、`tarball_url`（プロジェクトパッケージ）と `outputs`（すべての完成動画リンク）を含みます。
  * `data.progress`：段階ごとに追加される進捗イベント配列（append-only ログ）であり、詳細なリアルタイム進捗の表示に使用できます。
* `created_at`：タスク作成時刻、Unix タイムスタンプ（秒）。
* `started_at`：タスク実行開始時刻、Unix タイムスタンプ（秒）。タスクがまだ開始されていない場合は null です。
* `finished_at`：タスク完了時刻、Unix タイムスタンプ（秒）。タスクが未完了の場合は null です。

## 履歴リストの照会

`action: retrieve_batch` を渡すと、現在ログインしている実行者の直近のタスク（作成時刻の降順）を取得できます。「マイ動画」リストページに使用できます。履歴リストはログイン ID ごとに分離されています。

**Request Body** には以下が含まれます。

| フィールド | 型 | 必須 | 説明 |
| - | - | - | - |
| `action` | string | はい | `retrieve_batch` に固定 |
| `limit` | int | いいえ | 返却件数、デフォルトは 20；有効範囲は 1–100 |
| `created_at_max` | int | いいえ | この Unix タイムスタンプより厳密に前のタスクのみを返す（境界値を含まず、ページネーション用） |
| `created_at_min` | int | いいえ | この Unix タイムスタンプより厳密に後のタスクのみを返す（境界値を含まず） |

### コード例

対応する CURL コードは以下のとおりです：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'
```

### レスポンス例

リクエストが成功すると、API は現在のユーザーの履歴タスクリストを返します：

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}
```

返却結果のフィールド説明は以下のとおりです：

* `count`：現在ログインしている実行者が閲覧可能なタスクの総数であり、時間条件または `limit` の影響を受けません。
* `items`：時間条件および `limit` によってフィルタリングされたタスク配列で、作成時刻の降順に並びます；各要素の形式は「単一タスクの照会」の返却結果と一致します。

## ポーリングの推奨事項

動画の生成には長い時間がかかるため、`status` は `pending → planning → producing → succeeded`（または `failed`）を経ます。`status` が `succeeded` または `failed` に変わるまで、5～10 秒ごとにポーリングすることを推奨します。トップレベルの `progress.percent` を使用してリアルタイムのプログレスバーを表示できます。**本インターフェースのポーリングは無料であり、クレジットを消費しません。**

## エラー処理

API の呼び出し時にエラーが発生した場合、API は対応するエラーコードとメッセージを返します。例：

* `401 invalid_token`：Unauthorized、無効または不足している認証トークン。
* `404 not_found`：Task not found、指定された task\_id は存在しません。
* `429 too_many_requests`：Too many requests、レート制限を超過しています。
* `500 api_error`：Internal server error、サーバーで問題が発生しました。

### エラーレスポンス例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

本ドキュメントを通じて、Maestro タスク照会 API を使用して単一タスクのステータスと結果を照会する方法、および現在のユーザーの履歴タスクリストを取得する方法をご理解いただけたと思います。本ドキュメントが、この API の連携と利用により役立つことを願っています。ご質問がある場合は、いつでも技術サポートチームまでお問い合わせください。

## 関連インターフェース

* [Maestro 動画生成 API 連携説明](/ja/guides/maestro/maestro_videos)：自然言語のプロンプト一文で字幕付きの完成動画を自動生成し、送信後に `task_id` を返します。その後、本インターフェースで結果をポーリングします。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.