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

# Veo Videos Generation API 接続説明

> Veo Video Generation 集成指南 - XHuoAPI

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

## 申請プロセス

APIを使用するには、まず [Veo Videos Generation API](https://api.xhuoapi.ai/documents/63e01dc3-eb21-499e-8049-3025c460058f) の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下のように表示されます：

![](https://cdn.xhuoapi.ai/q6ytrc.png)

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

初回申請時には無料のクレジットが付与され、このAPIを無料で使用できます。

## 基本使用

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

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

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

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

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

* `model`：生成する動画のモデル。主に `veo2`、`veo2-fast`、`veo3`、`veo31`、`veo31-fast`、`veo31-fast-ingredients`、および `veo3-fast` モデルがあります。
* `action`：今回の動画生成タスクのアクション。主に3つのアクションが含まれます：文生動画（`text2video`）、図生動画（`image2video`）、1080p動画の取得（`get1080p`）。
* `image_urls`：図生動画アクション `image2video` を選択した場合に必ずアップロードする必要がある先頭と末尾のフレーム参照画像のリンク。最大で3枚の参照画像をアップロードできます。
* `resolution`：生成する動画の解像度を選択します。`veo31`モデルは4k解像度をサポートしていますが、他のモデルはサポートしていません。すべてのモデルは1080pおよびgif解像度をサポートしており、この値を指定しない場合はデフォルトで720p解像度が使用されます。主に：`1080p`、`gif`、`4k`。
* `prompt`：プロンプト。
* `callback_url`：結果をコールバックするURL。

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

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

***

### 🔑 重要ルール説明

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

***

### ⚠️ 注意事項

* **唯一の強制画像入力モデル**：`veo31-fast-ingredients` は画像を必ず入力する必要があります（1-3枚）、さもなければ実行できません。
* **画像数の制限**：
  * `veo31-fast-ingredients` を除き、他のモデルは最大 **3枚** の画像入力をサポートします。

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

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

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

```json theme={null}
{
  "success": true,
  "task_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
  "trace_id": "9906dac0-1516-41dc-9fe3-067ca1ba8269",
  "data": [
    {
      "id": "253eedc47f1c4eb2a370ed2312168f4b",
      "video_url": "https://platform.cdn.xhuoapi.ai/veo/dd01fc69-e1f7-4b68-aa8c-463f6b748d11.mp4",
      "created_at": "2025-07-25 16:07:43",
      "complete_at": "2025-07-25 16:10:28",
      "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.xhuoapi.ai/v1/veo/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "veo2",
  "prompt": "白いセラミックのコーヒーマグが光沢のある大理石のカウンタートップにあり、朝の窓の光が当たっています。カメラはマグの周りを360度ゆっくり回転し、ハンドルのところで一時停止します。"
}'
```

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

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

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

* `model`：生成動画のモデル、主に `veo2`、`veo2-fast`、`veo3`、`veo3-fast` があります。
* `image_urls`：画像から動画生成アクション `image2video` を選択した場合にアップロードする必要がある先頭と末尾のフレーム参考画像リンク。
* `prompt`：プロンプト。

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

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

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

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

対応するPythonコード：

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/veo/videos"

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

payload = {
    "action": "image2video",
    "model": "veo2",
    "prompt": "踊らせて",
    "image_urls": ["https://cdn.xhuoapi.ai/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.xhuoapi.ai/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.xhuoapi.ai/hacabc.png" width="500" className="m-auto" />
</p>

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

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

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

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

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

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

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/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.xhuoapi.ai/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`：生成動画のモデル、主に `veo2`、`veo2-fast`、`veo3`、`veo3-fast` があります。
* `aspect_ratio`：動画のサイズ、現在サポートされているのは `16:9`、`16:9`、`3:4`、`4:3`、`1:1` で、デフォルトは `16:9` です。
* `translation`：プロンプトの自動翻訳を有効にするかどうか、デフォルトは `false` です。
  記入例は以下の通りです：

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/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.xhuoapi.ai/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.xhuoapi.ai/tbcnai.png)

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

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

<p>
  <img src="https://cdn.xhuoapi.ai/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.xhuoapi.ai/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.xhuoapi.ai/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の接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。