メインコンテンツへスキップ
Maestro タスク照会 API の主な機能は、Maestro 動画生成 API(POST /maestro/videos)が返すタスク ID を通じて、そのタスクの実行状態と最終結果を照会することです。 本ドキュメントでは、Maestro タスク照会 API の連携ガイドを詳しく紹介します。動画生成は非同期タスクであるため、送信後は本インターフェースを使用して進捗と完成動画をポーリングで取得する必要があります。ポーリングは無料で、クレジットを消費しません。 POST https://api.acedata.cloud/maestro/tasks

申請手順

Maestro タスク照会 API を使用するには、まず Ace Data Cloud コンソール で API Token を取得し、控えておいてください。 まだログインまたは登録していない場合は、ログインページに自動的に移動して登録とログインを促され、完了後に自動的に現在のページへ戻ります。 1 つの API Token でプラットフォームのすべてのサービスを呼び出せるため、サービスごとに個別申請する必要はありません。 初回申請時には無料枠が付与され、無料で体験できます。残高が不足した場合は、コンソール で共通残高をチャージできます。
📘 完全なドキュメント:Maestro タスク照会 API →

単一タスクの照会

動画タスクの作成方法については、ドキュメント Maestro 動画生成 API を参照してください。ここでは、その返却されたタスク ID の例として f57e99c4f60f4373a15517742ce2357d を使用し、その状態と結果を照会する方法を説明します。

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

Request Headers には以下が含まれます:
  • accept:JSON 形式のレスポンス結果を受け取ることを指定します。ここでは application/json を指定します。
  • authorization:API を呼び出すためのキーです。申請後、直接プルダウンから選択できます。
  • content-type:リクエストボディの形式です。ここでは application/json を指定します。
Request Body には以下が含まれます:

コード例

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

レスポンス例

リクエストが成功すると、API はこの動画タスクのステータスと結果を返します。タスク完了時のレスポンス例は以下のとおりです(variants 配列には完成動画が 1 件含まれます)。
レスポンス結果のフィールドについては、以下のとおりです。
  • 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:選択した言語の完成動画オブジェクトを 1 件含みます。lang、aspect、title、output_url(完成動画のダウンロード URL)などを含みます。
    • data.project:プロジェクト全体の成果物。tarball_url(プロジェクトパッケージ)および outputs(完成動画リンク)を含みます。
    • data.progress:フェーズごとに追加される進捗イベントの配列(追記専用ログ)。詳細なリアルタイム進捗の表示に使用できます。
  • created_at:タスクの作成時刻。Unix タイムスタンプ(秒)。
  • started_at:タスクの実行開始時刻。Unix タイムスタンプ(秒)。タスクがまだ開始されていない場合は null です。
  • finished_at:タスク完了時刻(Unixタイムスタンプ、秒)。タスクが未完了の場合は null。

履歴リストの照会

action: retrieve_batch を渡すことで、現在ログインしている実行者の最新タスク(作成時刻の降順)を取得できます。「マイ動画」リストページに使用できます。履歴リストはログイン ID ごとに分離されています。 Request Body には以下が含まれます:

コード例

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

レスポンス例

リクエストが成功すると、API は現在のユーザーの履歴タスクリストを返します:
返却結果のフィールドの説明は以下のとおりです:
  • count:現在ログインしている実行者が閲覧可能なタスクの総数であり、時間条件や limit の影響を受けません。
  • items:時間条件および limit によってフィルタリングされたタスク配列で、作成時刻の降順に並びます;各要素の形式は「単一タスクの照会」の返却結果と一致します。

ポーリングの推奨事項

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

エラー処理

API の呼び出し時にエラーが発生した場合、API は対応するエラーコードと情報を返します。例:
  • 401 invalid_token:未認証、無効な認証トークン、または認証トークンがありません。
  • 404 not_found:タスクが見つかりません。指定された task_id は存在しません。
  • 429 too_many_requests:リクエストが多すぎます。レート制限を超過しました。
  • 500 api_error:内部サーバーエラー。サーバーで問題が発生しました。

エラーレスポンス例

結論

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

関連インターフェース

  • Maestro 動画生成 API 連携説明:自然言語のプロンプトを一文入力することで、字幕付きの完成動画を自動生成します。送信後に task_id が返され、その後、本インターフェースで結果をポーリングします。