メインコンテンツへスキップ
Maestro は Agent ネイティブの動画制作インターフェースです。自然言語の一文 prompt で作りたい動画を説明し(必要に応じて file_urls で参考画像 / 動画 / 音声を添付)、ヘッドレスな「AI ディレクター」が自動的に企画選定、スクリプト作成、映像生成、ナレーション、BGM、合成、レンダリングを完了し、最終的に字幕付きの完成動画を生成して CDN にアップロードします。 本記事では、Maestro 動画生成 API の連携ガイドを詳しく紹介し、API を迅速に統合してその能力を十分に活用できるよう支援します。 これは非同期タスクインターフェースです。送信後すぐに task_id が返され、その後 Maestro タスク照会 API(POST /maestro/tasks)を通じてポーリングし、結果を取得します(ポーリングは無料で課金されません)。既存の動画を引き続き反復するには、action: remix / edit / extend と ref_task_id を組み合わせて使用できます。

申請手順

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

基本的な使用方法

POST https://api.acedata.cloud/maestro/videos 最も基本的な使い方では、自然言語の prompt を渡すだけで、AIディレクターがスクリプト、映像、ナレーション、編集を自動的に決定します。ここでは、設定が必要なリクエストヘッダーとリクエストボディについて説明します。 Request Headers には以下が含まれます:
  • accept:受け取るレスポンス結果の形式を指定します。ここでは application/json、つまり JSON 形式を指定します。
  • authorization:API を呼び出すためのキーです。申請後、直接ドロップダウンから選択できます。
  • content-type:リクエストボディの形式です。ここでは application/json を指定します。
Request Body には主に以下が含まれます:
  • prompt:作成する動画を自然言語で説明します(テーマ、表示する内容、スタイル、対象視聴者)。
  • langs:完成動画の言語配列です。1回につき1種類のみ渡します。例:["zh-cn"]。デフォルトは ["zh-cn"]。
  • aspect:画面アスペクト比。9:16(デフォルト)/ 16:9 / 1:1。
  • duration:目標の長さ(秒)。デフォルトは 30。
リクエストボディのすべてのフィールドを以下の表に示します: 以下では、具体例を使って説明します。中国語の縦向き・20 秒の科学解説ショート動画を生成する場合、対応する CURL コードは以下のとおりです:
対応する Python コードは以下のとおりです:
実行をクリックすると、すぐに以下のような結果が返されます:
レスポンス結果のフィールドについては、以下のとおりです。
  • success:このタスクが正常に送信されたかどうか。
  • task_id:今回の動画生成タスクの ID。後続で Maestro タスク照会 API を使用して結果をポーリングします。
  • trace_id:このリクエストのトラッキング ID。問題が発生した場合は、技術サポートによる調査のために提供できます。
動画の生成には時間がかかるため、API はここで直ちに task_id を返し、動画のレンダリング完了を待ちません。続いて、task_id を使用して結果をポーリングする必要があります。詳細は「結果の取得」セクションを参照してください。

動画タイプとスタイルの指定(scenario / style)

scenario を渡さない場合は AI が自動的に判断します(auto と同等)。動画を特定のタイプに固定したい場合は、明示的に指定してください。たとえば、縦型ショートドラマを作成する場合は、以下のように指定できます。
  • scenario:動画タイプ。ここでは drama(キャラクター + セリフのショートドラマ)に設定します。
  • style:ビジュアルスタイル。ここでは cinematic(映画のような質感)に設定します。
記入例の CURL コードは以下のとおりです。
一般的な組み合わせ:
  • 解説ショート動画:scenario: "narrated"。
  • 自動字幕:scenario: "captions"。file_urls を使用して元動画を渡す必要があります。
  • デジタルアバター / ナレーション:scenario: "avatar"。file_urls を使用して人物画像を 1 枚渡す必要があります。
  • ショートドラマ:scenario: "drama"(キャラクター + セリフ)。
  • style はビジュアルスタイルのプリセットです(例:modern / neon / luxury)。タイプは変更せず、見た目の印象のみに影響します。
  • voice はナレーションの声質を指定するために使用します(例:warm-female / deep-male)。言語とは関係なく、言語をまたいで共通で使用できます。
返される結果は「基本的な使用方法」と同様で、同じく直ちに task_id が返されます。

完成動画の言語

1 つのタスクでは、1 つの言語による 1 本の完成動画のみが納品されます。langs には ["zh-cn"] または ["en"] のように 1 つの言語コードのみを含めることができます。複数の言語を渡すと 400 が返されます。異なる言語の動画が必要な場合は、それぞれ個別にタスクを作成してください。言語の選択によって秒単価は変わりません。

既存動画をベースにした反復(remix / edit / extend)

action と前回のタスクの ref_task_id を渡すことで、元プロジェクトをベースに差分修正を行えます(例:「第 2 幕のタイトルを変更する」「ナレーションを変更する」「全体を暗くする」)。小規模な変更は迅速に処理され、大規模な変更では再作成されます。
  • remix:元動画の構成をベースに再解釈します(テーマを維持し、表現を調整)。
  • edit:指定した部分を細かく修正します(例:タイトル変更、ナレーション変更、カラー調整)。
  • extend:元動画をベースにコンテンツを拡張します。
返される結果も同様に新しい task_id が直ちに返され、それをポーリングすることで反復後の完成動画を取得できます。

結果の取得

動画生成には比較的長い時間がかかるため、このインターフェースは送信後に直ちに task_id を返します。これを使用して Maestro タスク照会 API で結果をポーリングする必要があります。
タスクが完了すると、完成動画情報が 1 件返されます(variants 配列内)。status は pending → planning → producing → succeeded(または failed)と遷移します。ポーリングは無料で、クレジットを消費しません。完全なレスポンス形式および履歴一覧の照会については、Maestro タスク照会 API 連携ガイド を参照してください。

課金

タスク成功後、実際に納品された完成動画の長さに応じて課金され、失敗時は課金されません。 課金時間は整数秒で計算され、リクエストした時間を超えません。完成動画の長さを取得できない場合は、リクエスト時間にフォールバックします。タスクの送信自体には別途課金されず、/maestro/tasks のポーリングは無料です。
すべてのシナリオ、アクション、言語に同一の価格が適用され、シナリオ倍率や言語追加料金はありません。各タスクでは、1 つの言語による 1 本の完成動画のみが納品されます。リクエストする目標時間は 5~300 秒に対応し、すべて 1080p / 30fps で出力されます。

エラー処理

API 呼び出し時にエラーが発生した場合、API は対応するエラーコードと情報を返します。例:
  • 400 invalid_request:不正なリクエスト。prompt の不足または無効なパラメータが原因の可能性があります。
  • 401 invalid_token:未認証。認証トークンが無効、または不足しています。
  • 403 forbidden:アクセス禁止。残高またはアクセス権が不足しています。
  • 429 too_many_requests:リクエストが多すぎます。レート制限を超過しています。
  • 500 api_error:内部サーバーエラー。サーバー側で問題が発生しました。

エラーレスポンス例

まとめ

本ドキュメントを通じて、Maestro 動画生成 API の使用方法をご理解いただけたと思います。自然言語の prompt を 1 文入力するだけで、スクリプト、素材、ナレーション、BGM、編集、字幕、完成動画のレンダリングまでを自動的に完了でき、動画タイプ、スタイル、声質、完成動画の言語の指定、および既存動画をベースにした反復にも対応しています。本ドキュメントが、API のより良い連携および利用の助けとなれば幸いです。ご不明な点がございましたら、いつでも技術サポートチームまでお問い合わせください。

関連インターフェース

  • Maestro タスク照会 API 連携ガイド:POST /maestro/videos が返す task_id を使用してタスクのステータスと結果を照会するか、履歴タスク一覧を取得します(ポーリング無料)。