prompt で作成したいビデオを説明し（オプションで file_urls に参考画像 / ビデオ / 音声を添付）、無頭の「AI ディレクター」が自動的にテーマ選定、脚本作成、映像生成、ナレーション、音楽、合成およびレンダリングを行い、最終的に字幕付きの完成品を生成して CDN にアップロードします。
この記事では、Maestro ビデオ生成 API の連携説明を詳しく紹介し、迅速に統合し、API の能力を十分に活用できるようにします。
これは 非同期タスク インターフェースです：提出後にすぐに task_id が返され、その後 Maestro タスククエリ API（POST /maestro/tasks）を通じて結果をポーリングして取得します（ポーリングは無料で課金されません）。既存のビデオに対して継続的にイテレーションを行うには、action: remix / edit / extend を ref_task_id と組み合わせて使用します。
申請プロセス
Maestro ビデオ生成 API を使用するには、まず Ace Data Cloud コンソール にアクセスして API トークンを取得し、保管してください。
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。
1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。 初回申請時には無料枠が付与され、無料で体験できます；枠が不足した場合は コンソール で共通残高をチャージできます。
📘 完全なドキュメント：Maestro ビデオ生成 API →
基本使用
POST https://api.acedata.cloud/maestro/videos
最も基本的な使い方は、自然言語の prompt を渡すだけで、AI ディレクターが自動的に脚本、映像、ナレーション、編集を決定します。ここでは、設定する必要があるリクエストヘッダーとリクエストボディについて理解します。
リクエストヘッダー には以下が含まれます：
accept：受け取りたいレスポンス結果の形式、ここではapplication/jsonを記入します。authorization：API を呼び出すためのキー、申請後に直接選択できます。content-type：リクエストボディの形式、ここではapplication/jsonを記入します。
prompt：作成するビデオを自然言語で説明します（テーマ、表示内容、スタイル、対象者）。langs：出力言語の配列、例["zh-cn", "en"]、デフォルトは["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"、Lite / Standard / Pro すべて対応。 - 自動字幕：
scenario: "captions"、file_urlsで元のビデオを渡す必要があり、Lite / Standard / Pro すべて対応。 - デジタルアバター / ボイスオーバー：
scenario: "avatar"、file_urlsで肖像を渡す必要があり、Standard / Pro 対応。 - ショートドラマ：
scenario: "drama"（キャラクター + セリフ）、Pro のみ対応。 styleはビジュアルスタイルのプリセット（例：modern/neon/luxury）で、タイプを変更せず、視覚的な印象にのみ影響します。voiceはナレーションの音色を指定するために使用します（例：warm-female/deep-male）、言語に依存せず、言語を超えて共通です。
task_id を返します。
多言語出力
langs に複数の言語を渡すことで、一度に多言語バージョンを生成できます。最初の言語が主言語で、その後の言語は同じ映像を再利用し、音声とレンダリングを追加するだけなので、言語が一つ増えるごとに +6 ポイントが追加されます。例：
variant が含まれます（Maestro タスククエリ API を参照）。
既存のビデオでのイテレーション（remix / edit / extend）
action と前回のタスクの ref_task_id を渡すことで、元のプロジェクトに基づいて差分修正を行うことができます（例：「第2幕のタイトルを変更する」「別の声にする」「全体を暗くする」）。小さな変更はすぐに、大きな変更は再作成されます：
remix：元のビデオ構造の上で再演出します（テーマを保持し、表現を調整）。edit：特定の部分を精緻化します（例：タイトルを変更、声を変更、色調を調整）。extend：元のビデオに基づいて内容を拡張します。
task_id を返し、それを使ってポーリングすることでイテレーション後の完成品を取得できます。
結果を取得
ビデオ生成には時間がかかるため、このインターフェースは提出後に即座にtask_id を返します。それを使って Maestro タスククエリ API で結果をポーリングする必要があります：
variant が含まれます）。status は pending → planning → producing → succeeded（または failed）を経過します。ポーリングは無料で、ポイントを消費しません。完全なレスポンス形式と履歴リストのクエリについては、Maestro タスククエリ API の接続説明を参照してください。
課金
タスクが完了した後、実際の完成品に基づいて課金され、失敗したタスクは課金されません。 課金は実際に納品された完成品の長さと言語数に基づき、課金時間はリクエスト時間を超えません。特定の言語が最終的に生成されなかった場合、その言語の +6 加算は請求されません。タスクの提出自体は別途課金されず、/maestro/tasks のポーリングは無料です。
単一の完成品のポイントは以下の式で計算されます：
drama 1.35× / avatar 1.15× / その他 1×。
エラー処理
API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：400 invalid_request：不正なリクエスト、promptが欠落しているか無効なパラメータが原因の可能性があります。401 invalid_token：未認証、無効または欠落した認証トークン。403 forbidden：禁止、残高不足またはアクセス権限が不十分。429 too_many_requests：リクエストが多すぎます、レート制限を超えました。500 api_error：内部サーバーエラー、サーバーで何かがうまくいきませんでした。
エラー応答の例
結論
この文書を通じて、Maestro動画生成APIの使用方法を理解しました：自然言語のpromptを1つ入力するだけで、スクリプト、素材、ナレーション、音楽、編集、字幕、完成品のレンダリングを自動的に行い、動画の種類、スタイル、音色、多言語出力を指定し、既存の動画に対しても反復処理をサポートします。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。
関連インターフェース
- MaestroタスククエリAPI接続説明：
POST /maestro/videosで返されるtask_idを使用してタスクの状態と結果を照会するか、履歴タスクリストを取得します（ポーリングは無料です）。