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を指定します。
prompt:作成する動画を自然言語で説明します(テーマ、表示する内容、スタイル、対象視聴者)。langs:完成動画の言語配列です。1回につき1種類のみ渡します。例:["zh-cn"]。デフォルトは["zh-cn"]。aspect:画面アスペクト比。9:16(デフォルト)/16:9/1:1。duration:目標の長さ(秒)。デフォルトは 30。
以下では、具体例を使って説明します。中国語の縦向き・20 秒の科学解説ショート動画を生成する場合、対応する CURL コードは以下のとおりです:
success:このタスクが正常に送信されたかどうか。task_id:今回の動画生成タスクの ID。後続で Maestro タスク照会 API を使用して結果をポーリングします。trace_id:このリクエストのトラッキング ID。問題が発生した場合は、技術サポートによる調査のために提供できます。
task_id を返し、動画のレンダリング完了を待ちません。続いて、task_id を使用して結果をポーリングする必要があります。詳細は「結果の取得」セクションを参照してください。
動画タイプとスタイルの指定(scenario / style)
scenario を渡さない場合は AI が自動的に判断します(auto と同等)。動画を特定のタイプに固定したい場合は、明示的に指定してください。たとえば、縦型ショートドラマを作成する場合は、以下のように指定できます。
scenario:動画タイプ。ここではdrama(キャラクター + セリフのショートドラマ)に設定します。style:ビジュアルスタイル。ここではcinematic(映画のような質感)に設定します。
- 解説ショート動画:
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 で結果をポーリングする必要があります。
variants 配列内)。status は pending → planning → producing → succeeded(または failed)と遷移します。ポーリングは無料で、クレジットを消費しません。完全なレスポンス形式および履歴一覧の照会については、Maestro タスク照会 API 連携ガイド を参照してください。
課金
タスク成功後、実際に納品された完成動画の長さに応じて課金され、失敗時は課金されません。 課金時間は整数秒で計算され、リクエストした時間を超えません。完成動画の長さを取得できない場合は、リクエスト時間にフォールバックします。タスクの送信自体には別途課金されず、/maestro/tasks のポーリングは無料です。
エラー処理
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を使用してタスクのステータスと結果を照会するか、履歴タスク一覧を取得します(ポーリング無料)。

