> ## 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.

# Veo Videos Generation API 接続説明

> Veo Video Generation API guide - Ace Data Cloud

本文では、Veo Videos Generation API の接続説明を紹介します。これは、カスタムパラメータを入力することで、Veo公式の動画を生成することができます。

## 申請プロセス

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

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

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

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

> 📘 完全なドキュメント：[Veo Videos Generation API →](https://platform.acedata.cloud/documents/veo-videos)

## 基本使用

まず、基本的な使用方法を理解します。これは、プロンプト `prompt`、生成アクション `action`、先頭と末尾のフレーム参照画像配列 `image_urls`、およびモデル `model` を入力することで、処理された結果を得ることができます。最初に、`action` フィールドを簡単に渡す必要があります。その値は `text2video` で、主に3つのアクションが含まれます：テキストから動画（`text2video`）、画像から動画（`image2video`）、1080p動画の取得（`get1080p`）。次に、モデル `model` を入力する必要があります。現在、主に `veo31-fast`、`veo3`、`veo31`、`veo3-fast`、および `veo31-fast-ingredients` モデルがあります。具体的な内容は以下の通りです：

<p>
  <img src="https://cdn.acedata.cloud/vv5pe8.png" width="500" className="m-auto" />
</p>

ここでは、リクエストヘッダーを設定しています。これには以下が含まれます：

* `accept`：受け取りたいレスポンス結果の形式。ここでは `application/json`、つまりJSON形式を記入します。
* `authorization`：APIを呼び出すためのキー。申請後、直接ドロップダウンから選択できます。

さらに、リクエストボディを設定しています。これには以下が含まれます：

* `model`：生成する動画のモデル。主に `veo31-fast`、`veo3`、`veo31`、`veo3-fast`、および `veo31-fast-ingredients` モデルがあります。
* `action`：今回の動画生成タスクのアクション。主に3つのアクションが含まれます：テキストから動画（`text2video`）、画像から動画（`image2video`）、1080p動画の取得（`get1080p`）。
* `image_urls`：画像から動画アクション `image2video` を選択した場合に必ずアップロードする必要がある参照画像のリンク。`veo31-fast-ingredients` は最大3枚（複数画像融合）、他のモデルは最大2枚（先頭と末尾のフレームモード）。
* `resolution`：生成する動画の解像度を選択します。`veo31`モデルは4k解像度をサポートし、他のモデルはサポートしていません。すべてのモデルは1080pおよびgif解像度をサポートし、この値を指定しない場合はデフォルトで720p解像度が使用されます。主に：`1080p`、`gif`、`4k`。
* `prompt`：プロンプト。
* `callback_url`：結果をコールバックするURL。
* `async`：オプション。`true`に設定すると、インターフェースはすぐに `task_id` を返し、`callback_url` を提供する必要がなくなります。その後、対応するタスククエリインターフェースを通じて結果をポーリングして取得します。

### 📌 モデル説明のまとめ

| **モデル名**                   | **サポートモード**                                    | **画像入力ルール**                                   |
| -------------------------- | ---------------------------------------------- | --------------------------------------------- |
| **veo3-fast**              | テキストから動画（画像なし）<br />画像から動画モード（画像あり）            | **1枚** → 先頭フレームモード<br />**2枚** → 先頭と末尾フレームモード |
| **veo31-fast**             | テキストから動画（画像なし）<br />画像から動画モード（画像あり）            | **1枚** → 先頭フレームモード<br />**2枚** → 先頭と末尾フレームモード |
| **veo31-fast-ingredients** | ❌ テキストから動画（サポートなし）<br />✅ **強制的に複数画像融合**（画像必須） | **1-3枚** → 複数画像融合モード（最大3枚）                    |
| **veo3**                   | テキストから動画（画像なし）<br />画像から動画モード（画像あり）            | **1枚** → 先頭フレームモード<br />**2枚** → 先頭と末尾フレームモード |
| **veo31**                  | テキストから動画（画像なし）<br />画像から動画モード（画像あり）            | **1枚** → 先頭フレームモード<br />**2枚** → 先頭と末尾フレームモード |

***

### 🔑 重要ルールの説明

1. **一般的なロジック**：
   * **画像入力なし** → 自動的にテキストから動画モードがトリガーされます。
   * **画像入力あり** → 画像から動画モードがトリガーされます（具体的な動作は画像の数によって決まります）。
2. **画像から動画モードのタイプ**：
   * **先頭フレームモード**（1枚の画像）：先頭フレームは入力画像に固定されます。
   * **先頭と末尾フレームモード**（2枚の画像）：先頭フレームと末尾フレームは入力画像に固定されます。
   * **複数画像融合モード**（1-3枚の画像）：`veo31-fast-ingredients` のみがサポートし、複数画像の内容を融合して動画を生成します。
3. **モード分類**：

* **ファストモード**：`veo3-fast`、`veo31-fast`、`veo31-fast-ingredients`。
* **クオリティモード**：`veo3`、`veo31`（生成品質が高い）。

***

### ⚠️ 注意事項

* **唯一の強制画像入力モデル**：`veo31-fast-ingredients` は画像を必ず入力する必要があります（1-3枚）、そうでないと実行できません。
* **画像数の制限**：
  * `veo31-fast-ingredients` は **1-3枚**の画像入力をサポートします（複数画像融合モード）。
  * 他のモデルは最大 **2枚**の画像入力をサポートします（先頭と末尾フレームモード）。

選択後、右側にも対応するコードが生成されていることがわかります。以下のように：

<p>
  <img src="https://cdn.acedata.cloud/pmwh4y.png" width="500" className="m-auto" />
</p>

「Try」ボタンをクリックするとテストを行うことができます。上の図のように、以下の結果が得られました：

```json theme={null}
{
  "success": true,
  "task_id": "697ea2fc-58fd-48c8-8191-29041ff23c3c",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b",
  "data": [
    {
      "id": "24ac06a5-9cc7-448f-802e-0b4db19f6e96",
      "video_url": "https://platform2.cdn.acedata.cloud/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a.mp4",
      "created_at": "2026-06-30T04:01:50.364Z",
      "complete_at": "2026-06-30T04:03:20.495Z",
      "state": "succeeded"
    }
  ]
}
```

返された結果には複数のフィールドがあり、以下のように説明します：

* `success`、この時点での動画生成タスクの状態。
* `task_id`、この時点での動画生成タスクID。
* `data`、この時点での動画生成タスクの結果。
  * `id`、この時点での動画生成タスクの動画ID。
  * `video_url`、この時点での動画生成タスクの動画リンク。
  * `created_at`、この時点での動画生成タスクの作成時間。
  * `complete_at`、この時点での動画生成タスクの完了時間。
  * `state`、この時点での動画生成タスクの状態。

満足のいく動画情報が得られたことがわかります。結果の `data` の動画リンクアドレスに基づいて生成されたVeo動画を取得するだけです。

また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURLのコードは以下の通りです：

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/veo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "veo31-fast",
  "prompt": "白いセラミックのコーヒーマグが光沢のある大理石のカウンタートップに置かれ、朝の窓の光が差し込んでいます。カメラはマグの周りを360度ゆっくり回転し、ハンドルのところで一時停止します。"
}'
```

## 画像から動画生成機能

もし、先頭と末尾のフレーム画像に基づいて動画を生成したい場合は、パラメータ `action` を `image2video` に設定し、先頭と末尾のフレーム画像リンクの配列 `image_urls` を入力する必要があります。

次に、生成動画をカスタマイズするために拡張する必要があるプロンプトを入力する必要があります。以下の内容を指定できます：

* `model`：生成動画のモデル、主に `veo31-fast`、`veo3`、`veo31`、`veo3-fast` および `veo31-fast-ingredients` があります。
* `image_urls`：画像から動画生成行動 `image2video` を選択した場合に必ずアップロードする必要がある参考画像リンク。
* `prompt`：プロンプト。

入力例は以下の通りです：

<p>
  <img src="https://cdn.acedata.cloud/8wvlqd.png" width="500" className="m-auto" />
</p>

入力が完了すると、自動的に以下のコードが生成されます：

<p>
  <img src="https://cdn.acedata.cloud/tgzfxi.png" width="500" className="m-auto" />
</p>

対応するPythonコード：

```python theme={null}
import requests

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

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

payload = {
    "action": "image2video",
    "model": "veo31-fast",
    "prompt": "踊らせて",
    "image_urls": ["https://cdn.acedata.cloud/7p1jhy.png"]
}

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

実行をクリックすると、以下のような結果が得られます：

```json theme={null}
{
  "success": true,
  "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87",
  "trace_id": "8bc68066-36de-41ef-ae5e-b7d61ff6aee8",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}
```

結果の内容が前述のものと一致していることがわかります。これにより、画像から動画生成機能が実現されました。

## 1080p動画取得機能

もし、既に生成されたVeo動画の1080pを取得したい場合は、パラメータ `action` を `get1080p` に設定し、1080pを取得する必要がある動画のIDを入力します。動画IDの取得は基本的な使用に基づいて行います。以下の図のように：

<p>
  <img src="https://cdn.acedata.cloud/hacabc.png" width="500" className="m-auto" />
</p>

この時点で動画のIDは次のようになります：

```json theme={null}
"id": "59f12222b1fa4fbe9331ff2400ad1583"
```

> 注意：ここでの動画の `video_id` は生成後の動画のIDです。動画を生成する方法がわからない場合は、前述の基本的な使用を参考にして動画を生成してください。

次に、生成動画をカスタマイズするために拡張する必要があるプロンプトを入力する必要があります。以下の内容を指定できます：

* `model`：生成動画のモデル、主に `veo31-fast`、`veo3`、`veo31`、`veo3-fast` および `veo31-fast-ingredients` があります。
* `video_id`：参考動画ID、1080p動画を取得するために使用します。

入力例は以下の通りです：

<p>
  <img src="https://cdn.acedata.cloud/k56fhn.png" width="500" className="m-auto" />
</p>

入力が完了すると、自動的に以下のコードが生成されます：

<p>
  <img src="https://cdn.acedata.cloud/8gn4cr.png" width="500" className="m-auto" />
</p>

実行をクリックすると、以下のような結果が得られます：

```json theme={null}
{
  "success": true,
  "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984",
  "trace_id": "a8922eec-6f50-4f77-8104-00ded071d59d",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4",
      "created_at": "2025-07-25 16:13:07",
      "complete_at": "2025-07-25 16:16:12",
      "state": "succeeded"
    }
  ]
}
```

結果の内容が前述のものと一致していることがわかります。これにより、1080p動画取得機能が実現されました。

## 指定動画サイズ生成

もし、カスタムサイズのVeo動画を生成したい場合は、パラメータ `aspect_ratio` を希望のサイズに設定します。次に、生成動画をカスタマイズするために拡張する必要があるプロンプトを入力する必要があります。以下の内容を指定できます：

* `model`：生成動画のモデル、主に `veo31-fast`、`veo3`、`veo31`、`veo3-fast` および `veo31-fast-ingredients` があります。
* `aspect_ratio`：動画のサイズ、現在サポートされているのは `16:9`、`16:9`、`3:4`、`4:3`、`1:1` で、デフォルトは `16:9` です。
* `translation`：プロンプトの自動翻訳を有効にするかどうか、デフォルトは `false` です。
  入力例は以下の通りです：

<p>
  <img src="https://cdn.acedata.cloud/xau4cm.png" width="500" className="m-auto" />
</p>

入力が完了すると、自動的に以下のコードが生成されます：

<p>
  <img src="https://cdn.acedata.cloud/55r589.png" width="500" className="m-auto" />
</p>

実行をクリックすると、以下のような結果が得られます：

```json theme={null}
{
  "success": true,
  "task_id": "d2b93290-ab0e-4d20-ae45-60c062a32687",
  "trace_id": "9834e64d-c8fe-43ae-8114-ee2b5f93d886",
  "data": [
    {
      "id": "fc667e7d3b8f44beaa61a3c339af0e50",
      "video_url": "https://platform.cdn.acedata.cloud/veo/d2b93290-ab0e-4d20-ae45-60c062a32687.mp4",
      "created_at": "2025-08-24 20:09:06",
      "complete_at": "2025-08-24 20:10:45",
      "state": "succeeded"
    }
  ]
}
```

結果の内容が上記と一致していることがわかります。これにより、指定サイズでの動画生成機能が実現されました。

## 非同期コールバック

Veo Videos Generation APIによる生成には比較的長い時間がかかり、約1〜2分必要です。APIが長時間応答しない場合、HTTPリクエストは接続を維持し続け、追加のシステムリソースを消費するため、本APIは非同期コールバックのサポートも提供しています。

全体の流れは、クライアントがリクエストを発行する際に、追加で`callback_url`フィールドを指定し、クライアントがAPIリクエストを発行した後、APIはすぐに結果を返し、現在のタスクIDを示す`task_id`フィールド情報を含みます。タスクが完了すると、生成された動画の結果がPOST JSON形式でクライアントが指定した`callback_url`に送信され、その中にも`task_id`フィールドが含まれているため、タスクの結果をIDで関連付けることができます。

以下の例を通じて、具体的にどのように操作するかを理解しましょう。

まず、WebhookコールバックはHTTPリクエストを受信できるサービスであり、開発者は自分が構築したHTTPサーバーのURLに置き換える必要があります。ここではデモのために、公開のWebhookサンプルサイト[https://webhook.site/を使用します。このサイトを開くとWebhook](https://webhook.site/を使用します。このサイトを開くとWebhook) URLが得られます。

![](https://cdn.acedata.cloud/tbcnai.png)

このURLをコピーすればWebhookとして使用できます。ここでのサンプルは`https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc`です。

次に、フィールド`callback_url`を上記のWebhook URLに設定し、対応するパラメータを入力します。具体的な内容は以下の通りです：

<p>
  <img src="https://cdn.acedata.cloud/rgivs2.png" width="500" className="m-auto" />
</p>

実行ボタンをクリックすると、すぐに結果が得られます。以下のようになります：

```json theme={null}
{
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"
}
```

少し待つと、`https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc`で生成された動画の結果を確認できます。以下のようになります：

![](https://cdn.acedata.cloud/238i32.png)

内容は以下の通りです：

```json theme={null}
{
  "success": true,
  "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed",
  "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56",
  "data": [
    {
      "id": "2f43ceed37944b4d836e1a1899dad0a1",
      "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4",
      "created_at": "2025-07-25 17:19:20",
      "complete_at": "2025-07-25 17:21:45",
      "state": "succeeded"
    }
  ]
}
```

結果には`task_id`フィールドがあり、他のフィールドは上記と似ています。このフィールドを通じてタスクの関連付けが可能です。

## エラーハンドリング

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

* `400 token_mismatched`：不正なリクエスト、パラメータが欠落または無効な可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが欠落または無効な可能性があります。
* `401 invalid_token`：認証されていない、無効または欠落した認証トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

### エラー応答の例

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## 結論

本ドキュメントを通じて、Veo Videos Generation APIを使用して入力プロンプトおよび初フレームの参照画像を通じて動画を生成する方法を理解しました。このドキュメントがAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。