> ## 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公式の動画を生成できる、Veo Videos Generation API の連携説明を紹介します。

## 申請手順

Veo Videos Generation API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications)で API Token を取得し、控えておいてください。

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

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

**1つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、サービスごとに個別で申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](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>

ここでは Request Headers を設定しており、以下を含みます：

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

また、Request Body を設定しており、以下を含みます：

* `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. **モード分類**：

* **Fast モード**：`veo3-fast`、`veo31-fast`、`veo31-fast-ingredients`。
* **Quality モード**：`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://cdn.acedata.cloud/assets/examples/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a-0b0c3113d691.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": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'
```

## 画像から動画を生成する機能

開始フレームと終了フレームの画像に基づいて動画を生成したい場合は、パラメータ `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": "Let it dance",
    "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`：1080p動画の取得に使用する参照動画ID。

入力例は以下のとおりです：

<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/](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 との連携および利用により役立つことを願っています。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。


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