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を指定します。
コード例
対応する CURL コードは以下のとおりです:レスポンス例
リクエストが成功すると、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が返され、その後、本インターフェースで結果をポーリングします。

