> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro ビデオ生成 API 連携説明

> Maestro AI Video Studio API guide - Ace Data Cloud

Maestro は **エージェントネイティブ**なビデオ制作インターフェースです：自然言語の `prompt` で作成したいビデオを説明し（オプションで `file_urls` に参考画像 / ビデオ / 音声を添付）、無頭の「AI ディレクター」が自動的にテーマ選定、脚本作成、映像生成、ナレーション、音楽、合成およびレンダリングを行い、最終的に字幕付きの完成品を生成して CDN にアップロードします。

この記事では、Maestro ビデオ生成 API の連携説明を詳しく紹介し、迅速に統合し、API の能力を十分に活用できるようにします。

これは **非同期タスク** インターフェースです：提出後にすぐに `task_id` が返され、その後 [Maestro タスククエリ API](/ja/guides/maestro/maestro_tasks)（`POST /maestro/tasks`）を通じて結果をポーリングして取得します（ポーリングは無料で課金されません）。既存のビデオに対して継続的にイテレーションを行うには、`action: remix` / `edit` / `extend` を `ref_task_id` と組み合わせて使用します。

## 申請プロセス

Maestro ビデオ生成 API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) にアクセスして API トークンを取得し、保管してください。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。

**1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料枠が付与され、無料で体験できます；枠が不足した場合は [コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。

> 📘 完全なドキュメント：[Maestro ビデオ生成 API →](https://platform.acedata.cloud/documents/maestro-videos)

## 基本使用

`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。

リクエストボディのすべてのフィールドは以下の表に示されています：

| フィールド | タイプ | 必須 | 説明 |
| - | - | - | - |
| `prompt` | string | はい | 作成するビデオを自然言語で説明します（テーマ、表示内容、スタイル、対象者）。脚本、映像、ナレーション、編集はすべて AI によって決定されます。 |
| `action` | string | いいえ | `generate`（デフォルト、新しいビデオを生成）/ `remix` / `edit` / `extend`（既存のビデオにイテレーションを行うには `ref_task_id` と組み合わせる必要があります）。 |
| `ref_task_id` | string | いいえ | `action` が remix / edit / extend の場合は必須：出発点となる過去のタスク `task_id` |
| `file_urls` | string\[] | いいえ | 参考メディア（画像 / ビデオ / 音声の URL）、例：出てくる製品画像、ロゴ、または字幕を追加する素材の断片。 |
| `langs` | string\[] | いいえ | 出力言語、例 `["zh-cn", "en"]`、デフォルトは `["zh-cn"]`。最初の言語が主言語；言語を追加するごとに映像を再利用し、ナレーション + レンダリングが追加されます、**言語ごとに +6 ポイント**。 |
| `aspect` | string | いいえ | `9:16`（デフォルト）/ `16:9` / `1:1`、統一出力 1080p/30fps。 |
| `duration` | int | いいえ | 目標時間（秒）、デフォルトは 30、**5–300 秒**をサポート。実際の完成品の長さに基づいて課金されますが、リクエスト時間を超えることはありません。 |
| `scenario` | string | いいえ | ビデオタイプ：`auto` / `narrated` / `captions` / `avatar` / `drama`。`captions` には元のビデオを、`avatar` には肖像を提供する必要があります。 |
| `style` | string | いいえ | ビジュアルスタイルのプリセット：`auto`（デフォルト）/ `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`、自由テキストもソフトプロンプトとして受け入れられます。`scenario` と交差せず、ルーティングを変更しません。 |
| `voice` | string | いいえ | ナレーションの音色（言語に依存せず、言語を超えて共通）：`auto`（デフォルト）/ `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male`。 |

具体的な例を通じて説明します。例えば、中英二言語、縦型、20秒の科学普及短編ビデオを生成したい場合、対応する CURL コードは以下の通りです：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'
```

対応する Python コードは以下の通りです：

```python theme={null}
import requests

url = "https://api.acedata.cloud/maestro/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

実行すると、すぐに結果が得られます。以下のようになります：

```json theme={null}
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}
```

返された結果のフィールドの説明は以下の通りです：

* `success`：今回のタスクが成功裏に提出されたかどうか。
* `task_id`：今回のビデオ生成タスクの ID、後で [Maestro タスククエリ API](/ja/guides/maestro/maestro_tasks) を使って結果をポーリングするために使用します。
* `trace_id`：今回のリクエストのトレース ID、問題が発生した場合に技術サポートに提供して特定するために使用します。

ビデオ生成には時間がかかるため、インターフェースはここで**即座に `task_id` を返します**。ビデオレンダリングが完了するのを待つわけではありません。次に `task_id` を使って結果をポーリングする必要があります。「結果を取得」セクションを参照してください。

## ビデオタイプとスタイルの指定（scenario / style）

`scenario` を指定しない場合、AI が自動的に判断します（`auto` と同等）。特定のタイプのビデオを固定したい場合は、明示的に指定します。例えば、**縦型ショートドラマ**を作成する場合、以下の内容を指定できます：

* `scenario`：ビデオタイプ、ここでは `drama`（キャラクター + セリフのショートドラマ）と設定します。
* `style`：ビジュアルスタイル、ここでは `cinematic`（映画の質感）と設定します。

サンプルの CURL コードは以下の通りです：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "二人のルームメイトが一匹の猫を巡って喧嘩し、また仲直りする、三幕の反転、結末は温かい",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'
```

一般的な組み合わせ方法：

* ナレーション短編：`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 ポイント**が追加されます。例：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "私たちのスマートカスタマーサービス製品を紹介し、3つのコアポイントを強調する",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'
```

タスクが完了すると、各言語に対応する結果の中に一つの `variant` が含まれます（[Maestro タスククエリ API](/ja/guides/maestro/maestro_tasks) を参照）。

## 既存のビデオでのイテレーション（remix / edit / extend）

`action` と前回のタスクの `ref_task_id` を渡すことで、元のプロジェクトに基づいて差分修正を行うことができます（例：「第2幕のタイトルを変更する」「別の声にする」「全体を暗くする」）。小さな変更はすぐに、大きな変更は再作成されます：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "オープニングタイトルをよりインパクトのあるものに変更し、全体の配色を少し暗くする"
}'
```

* `remix`：元のビデオ構造の上で再演出します（テーマを保持し、表現を調整）。
* `edit`：特定の部分を精緻化します（例：タイトルを変更、声を変更、色調を調整）。
* `extend`：元のビデオに基づいて内容を拡張します。

返される結果も即座に新しい `task_id` を返し、それを使ってポーリングすることでイテレーション後の完成品を取得できます。

## 結果を取得

ビデオ生成には時間がかかるため、このインターフェースは提出後に即座に `task_id` を返します。それを使って [Maestro タスククエリ API](/ja/guides/maestro/maestro_tasks) で結果をポーリングする必要があります：

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d"
}'
```

タスクが完了すると、完成品情報が返されます（各言語に対応する `variant` が含まれます）。`status` は `pending → planning → producing → succeeded`（または `failed`）を経過します。**ポーリングは無料で、ポイントを消費しません**。完全なレスポンス形式と履歴リストのクエリについては、[Maestro タスククエリ API の接続説明](/ja/guides/maestro/maestro_tasks)を参照してください。

## 課金

**タスクが完了した後、実際の完成品に基づいて課金され、失敗したタスクは課金されません。** 課金は実際に納品された完成品の長さと言語数に基づき、課金時間はリクエスト時間を超えません。特定の言語が最終的に生成されなかった場合、その言語の +6 加算は請求されません。タスクの提出自体は別途課金されず、`/maestro/tasks` のポーリングは無料です。

単一の完成品のポイントは以下の式で計算されます：

```
ポイント = 完成品の長さ（秒） × 0.60 × シーン倍率 + 6 × max(言語数 − 1, 0)
```

Maestro は **0.60 ポイント/実際の完成品の秒数**で課金され、5–300 秒、最大 4 言語および 1080p / 30fps 出力をサポートします。すべてのアクションとシーンが使用可能です。

シーン倍率：`drama` 1.35× / `avatar` 1.15× / その他 1×。

| 例 | ポイント |
| - | -: |
| Lite 30 秒 | 6 |
| Standard 30 秒 | 18 |
| Standard 60 秒 | 36 |
| Standard 120 秒 | 72 |
| Pro 30 秒 | 36 |
| Pro 300 秒 | 360 |
| 実際に納品された言語が一つ増えるごとに | +6 |
| `/maestro/tasks` のポーリング | 無料 |

## エラー処理

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例えば：

* `400 invalid_request`：不正なリクエスト、`prompt` が欠落しているか無効なパラメータが原因の可能性があります。
* `401 invalid_token`：未認証、無効または欠落した認証トークン。
* `403 forbidden`：禁止、残高不足またはアクセス権限が不十分。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "取得に失敗しました"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

この文書を通じて、Maestro動画生成APIの使用方法を理解しました：自然言語の`prompt`を1つ入力するだけで、スクリプト、素材、ナレーション、音楽、編集、字幕、完成品のレンダリングを自動的に行い、動画の種類、スタイル、音色、多言語出力を指定し、既存の動画に対しても反復処理をサポートします。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。

## 関連インターフェース

* [MaestroタスククエリAPI接続説明](/ja/guides/maestro/maestro_tasks)：`POST /maestro/videos`で返される`task_id`を使用してタスクの状態と結果を照会するか、履歴タスクリストを取得します（ポーリングは無料です）。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.