> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# VEO 3.1 公式動画生成
> Google Veo 3.1 公式リレーチャンネルの完全ガイド: Google AI Studio への透過的なパススルー、リクエストごとの課金で $0.3 / $1.2、柔軟な 4 / 6 / 8 秒の長さ、720p / 1080p / 4k の階層、そして手間のないオンボーディング — グループや課金モードの切り替えは不要です。
## 概要
**VEO 3.1 Official** は、Google Veo 3.1 向けの APIYI による**公式リレーチャネル**です。Google AI Studio の `veo-3.1-generate-preview` / `veo-3.1-fast-generate-preview` 非同期エンドポイントへの透過的なパススルーであり、モデル ID、レスポンスフィールド、制約事項はすべてアップストリームと同一です。**リクエストごとの課金**に対応し、**`Default` グループで呼び出し可能** — 現在利用できる中で最も導入の手間が少ない、公式品質の Veo 3.1 チャネルです。
**🎬 ハイライト**: Google AI Studio への透過的なパススルー + ネイティブ同期オーディオ + 柔軟な 4 / 6 / 8 秒の動画長 + 3段階の解像度ティア（720p / 1080p / 4k）+ \$0.3 からのリクエスト単位課金 + **`Default` グループ + リクエスト単位課金または従量課金優先トークン**（専用グループは不要、純粋な従量課金は非対応）。**広告ショート動画、EC 用アセット、ソーシャルメディアコンテンツ、製品デモ**など、最もシンプルな導入方法で公式水準の品質を必要とする用途に適しています。
**⚠️ `/content` 経由でダウンロードし、自身で再ホストしてください**: `status: "completed"` になったら、エンドユーザーに配信する前に **`GET /v1/videos/{task_id}/content` を呼び出して MP4 バイナリを取得**し、ご自身の OSS / CDN に保存してください。完了レスポンスには `video_url`（認証不要の直接リンク）が含まれる**場合もあります**が、これは**約24時間後に期限切れ**となり（`expires_at` を参照）、**すべてのタスクで保証されているわけではありません**。そのため、一時的なプレビューにのみ使用し、永続的なアドレスとしては決して使用しないでください。詳細は以下の [API エンドポイント](#api-endpoints) を参照してください。
`POST /v1/videos`。テキストのみから動画を生成します — JSON リクエストボディを使用する、最もシンプルなエントリーポイントです。
`POST /v1/videos` + `input_reference` のマルチパートアップロードにより、静止画像をアニメーション化してクリップにします。
既存の [VEO 3.1 (リバースチャネル)](/en/api-capabilities/veo/overview) との比較・選定マトリクスです。
iCover ビジュアルテストツールでこのエンドポイントを直接デバッグできます — コードは不要です。
送信された動画タスクの表示と動画リンクのダウンロードを APIYI コンソールで行えます — API 以外の照会エントリーポイントです。
## AI Agentにインテグレーションを任せる
このプロジェクトにVEO 3.1 Officialのテキストからの動画生成および画像からの動画生成を統合 / トラブルシューティングしてください。
コードに触れる前にドキュメントを読んでください：このページのプレーンテキスト版を取得するには [https://docs.apiyi.com/en/api-capabilities/veo-3-1-official/overview.md](https://docs.apiyi.com/en/api-capabilities/veo-3-1-official/overview.md) を取得します。より詳細なパラメータについては、同様にテキストからの動画生成と画像からの動画生成のページの末尾に`.md`を追加してください。
要件：
1. 同期待機ではなく、3ステップの非同期フローを使用してください。このチャネルは**非同期専用**です：`POST /v1/videos`でジョブを送信して`task_id`を取得し、`status`が`completed`になるまで**8〜10秒ごと**に`GET /v1/videos/{task_id}`をポーリングして、`GET /v1/videos/{task_id}/content`からMP4をダウンロードします。**webhookはなく、ポーリングのみ**です。コールバック設定を探さないでください。
2. 動画の取得（**このモデルで最も重要な項目**）：MP4バイナリストリームの信頼できる情報源として`/content`エンドポイントを扱ってください。そのリクエストには\*\*`Authorization`ヘッダーを含める必要があります\*\*。そのためフロントエンドでvideoタグ`src`に直接設定することは**できません**（認証ヘッダーのないブラウザリクエストは401になります）。完了時のレスポンスには認証不要の`video_url`直リンクが含まれる**場合があります**が、約24時間後に期限切れとなり（`expires_at`を参照）、**すべてのタスクで保証されているわけではありません**。コード内でこれに依存しないでください。存在する場合は簡単なプレビューに使用し、それ以外は`/content`を経由してください。正しいアプローチ：**ステータスが`completed`になったら直ちにサーバーサイドでMP4をダウンロードし、独自のオブジェクトストレージまたはCDNに再ホスト**した上で、エンドユーザーに独自のURLを提供します。**リモートの動画は約24時間しか保持されないため、長期的なアドレスとして`task_id`に依存しないでください**。`/content`が400を返した場合は、最大約30秒間、4秒ごとに再試行してください。`status`が`completed`に切り替わった直後の最大約20秒間は400が返されるウィンドウが存在します（エラーには`task status is IN_PROGRESS`と表示されます）。curlでダウンロードする場合は`-f --retry-all-errors`を追加する必要があります。そうしないと400が再試行されず、エラーJSONが動画ファイルに書き込まれてしまいます。**`502`は別物です**：プロバイダーがファイルを取得できず、再試行しても解決しないため、2回試行した後に停止し、タスクを失敗としてマークして`task_id`を記録してください。無制限のリトライループは絶対に作成しないでください。
3. 段階的なタイムアウト：POST送信には30秒を見込んでください（マルチパートの参照画像アップロードは遅くなる可能性があります）。ポーリング待機時間は解像度ごとに制限を設けてください — 720pと1080pは**3分**、4Kは**10分**です。単一の値をハードコードするのではなく、設定項目として管理してください。
4. モデルとパラメータ：モデル名は`veo-3.1-fast-generate-preview`（より安価で、普段使いに適しています）または`veo-3.1-generate-preview`（標準ティア）のいずれかです。再生時間フィールドは\*\*`duration`ではなく`seconds`**であり、**文字列である必要があります**（`"4"` / `"6"` / `"8"`） — 数値はサーバーによって拒否されます。**フィールド名を`duration`にしてもエラーは発生しません：通知なく無視され、再生時間は4秒にフォールバックします** — これがまさに「8秒を指定したのに4秒になった」という問題の原因です。**再生時間と解像度は連動しています**：`1080p`と`4k`はどちらも**`"8"`の`seconds`のみ\*\*を受け入れ、`"4"`や`"6"`を渡すとエラーになります。3つの再生時間すべてを許可するのは`720p`のみです。したがってUIでユーザーに解像度と再生時間を一緒に選択させる場合は、無効な組み合わせを提示するのではなく、ペアで制約を設けてください。4Kにはさらにモデル`veo-3.1-generate-preview`と10分のタイムアウトが必要です。4Kのレンダリングは1080pより4〜6倍遅く、ファイルサイズは約10倍になりますが、**呼び出しごとの課金は再生時間と解像度の両方に依存しません（4Kでも追加料金はかからず、節約にもなりません）**。そのためデフォルトは1080pとし、4Kは明示的なユーザー選択にしてください。
5. 画像からの動画生成における3つの厳格な制約：リクエストはJSONではなく\*\*`multipart/form-data`**でなければなりません。画像フィールド名は**正確に`input_reference`**でなければならず（`image`、`reference`、`input_image`はすべて無視されます）、**受け入れられる画像は1枚のみ**です（余分な画像は通知なく無視されます）。リモートURLは**受け付けられない**ため、ファイルまたはbase64をアップロードしてください。受け入れ可能なタイプは`image/jpeg`、`image/png`、`image/webp`です。また、このチャネルでは**最初/最後のフレーム指定や複数参照の機能は提供されていない\*\*ため、それらの機能に関してGoogle公式のVeo 3.1ドキュメントに沿った実装は行わないでください。マルチパートモードでは、`metadata.*`フィールドは`resolution`、`aspectRatio`、`seed`というプレーンなフォームフィールドにフラット化されます。
6. **`generateAudio`を送信しないでください。** Veo 3.1はネイティブに音声を生成しますが、そのパラメータを渡すと上流が`INVALID_ARGUMENT`を返します。効果音、音声、環境音を制御するには、プロンプト内にその意図を含めてください。このチャネルには音声フィールド自体が存在しません。
7. 課金とエラー：**課金は呼び出しごと、モデル名別**であり、再生時間、解像度、参照画像を渡したかどうかには依存しません。非同期モードでは、**生成の失敗、モデレーションによるブロック、オーバーロードエラーはすべて課金されません — 課金されるのは`completed`ステータスのみです** — そのため、自動再試行による二重課金のリスクはありません。エラー処理について：接頭辞`PUBLIC_`が付いたエラーは上流のモデレーションブロックであり、課金対象外で、プロンプトを調整した後に直接再試行できます。`5xx`または`INTERNAL`は一時的な上流エラーであり、同じシード値で1〜2回再試行する価値があります。タスクが`failed`になった場合は、通常モデレーション、上流のキャパシティ不足、または取得不能な動画ファイルが原因であり、同様に課金されません（課金された場合は自動的に返金されます）。理由は`error.message`に含まれるため、ログに記録してください。
8. 注意すべきtoken設定：このモデルでは、tokenが**呼び出しごとの課金**または**従量課金優先**に設定されている必要があります。**通常の従量課金はサポートされていません**。呼び出しが課金モードに関するエラーで失敗した場合は、コンソールでtokenを切り替えてください。
9. キーは環境変数`APIYI_API_KEY`から読み込み、ベースURLとして[https://api.apiyi.com/v1](https://api.apiyi.com/v1) を使用してください。決してハードコードしたり、gitにコミットしたりしないでください。
10. 完了したら、実際にテキストからの動画生成と画像からの動画生成の呼び出しを1回ずつ実行し、生成された動画とそれら2回の呼び出しの費用を提示してください。
| 要件 | 回避できる落とし穴 |
| - | - |
| MP4を直ちにダウンロードして再ホストする | `video_url`は保証されておらず約24時間で期限切れとなり、リモートコピーも約24時間しか保持されないため、`task_id`や直リンクを恒久的なアドレスとして扱うと最終的に失敗します |
| フロントエンドから`/content`を直接叩けない | そのエンドポイントには認証ヘッダーが必要なため、ブラウザからのリクエストは401を返し、video要素は黒い画面のままになります |
| 同期的に待機せずポーリングを行う | 公式リレーは非同期エンドポイントのみを公開しておりwebhookがないため、単一のブロッキングHTTP呼び出しは機能しません |
| 再生時間は解像度と連動している | `1080p`と`4k`はどちらも`"8"`の`seconds`のみを受け入れるため、デフォルトで1080pに`"4"`を指定するとエラーになります — 3つすべてを許可するのは720pのみです |
| `seconds`は数値ではなく文字列 | フィールド名も`duration`ではありません。どちらかを誤るとサーバーによって拒否されます |
| 失敗時は課金されない | 課金されるのは`completed`のみであるため、安全に自動再試行を行えます |
| tokenは呼び出しごとまたは従量課金優先である必要がある | 通常の従量課金では実行できず、そのエラーはコードとは関係がありません |
## APIYI の VEO 3.1 公式版を使う理由
Google 公式 / Vertex AI チャネルのドロップイン代替で、**導入時の手間**, **安定性**, **コスト** にまたがる本番シナリオ向けに最適化されています:
Google AI Studio の Veo 3.1 非同期エンドポイントへの透過的なパススルーです。**Model IDs（`veo-3.1-generate-preview` / `veo-3.1-fast-generate-preview`）は上流と完全に一致し**、リクエストとレスポンスのフィールドおよび制約も 1 対 1 で対応しています。
呼び出しは **`Default` グループ** で動作し、**Pay-per-request または Pay-as-you-go Priority Tokens** を利用できます（純粋な Pay-as-you-go はサポートされません）。**専用のグループ切り替えは不要**で、既存の Pay-per-request Tokens をそのまま使えます。Veo 3.1 における、最も手間の少ない公式品質チャネルです。
透過プロキシ付きの集約アカウントプールで、バッチ撮影、広告パイプライン、大規模本番を線形にスケールできます。**Google のアカウントごとのティア上限はありません**。
`veo-3.1-fast-generate-preview` \$0.3/req、`veo-3.1-generate-preview` \$1.2/req で、4/6/8 秒および 720p/1080p/4k で一律です。**Google の公式 8秒 1080p と比べて 62～68% 節約**でき、[チャージ特典](/ja/faq/recharge-promotions) を組み合わせるとさらにお得になります。失敗したタスクは課金されません。
**海外サーバーやプロキシは不要**です — 中国本土のデータセンター、住宅回線、または海外ノードから `api.apiyi.com` に直接接続できます。Google AI Studio / Vertex AI の越境設定は一切不要です。
当社チームは動画生成に深い知見があります: prompt engineering、解像度選定、バッチ制作、後処理まで対応します。企業のお客様向けに、PoC から本番までの技術サポートをフルで提供します。
## 主な機能
Veo 3.1 は **同期オーディオ付きの動画**（環境音、会話、音楽）をネイティブに出力します。別途オーディオのポストプロダクションは不要です。プロンプトで音声の意図を指定してください。
`seconds` 文字列 enum: `"4"` / `"6"` / `"8"`. **1リクエストごとの課金で、長さは価格に影響しません**。1080p / 4k ティアには `"8"` が必要です。
`720p` / `1080p` / `4k`、**1リクエストごとの一律料金**。横向き（`16:9`）と縦向き（`9:16`）を自由に切り替えられます。
Veo 3.1 は、カメラの動き、物体物理、キャラクター表現の忠実度でこのティアをリードします。豊富なカメラ言語キーワード（push/pull/pan/dolly、low/high angles）に対応しています。
1 枚の画像を視覚的なアンカーとしてアップロードし、静止コンテンツをアニメーション化します。[画像から動画へ](/ja/api-capabilities/veo-3-1-official/image-to-video) を参照してください。
submit はすぐに `task_id` を返します。ステータスは個別にポーリングし、最終動画をダウンロードできます。バッチ管理や失敗時の再開フローに最適です。
`base_url=https://api.apiyi.com/v1` + `Bearer` 認証。生の HTTP または OpenAI SDK の低レベル `client.post()` で動作します。
非同期モードでは、失敗した生成、コンテンツポリシーによる拒否、パラメータエラーは **課金されません**。**`status=completed` のタスクのみ課金対象です**。
## 料金
APIYIは**リクエストごとの従量課金**です — サポート対象の継続時間/解像度の組み合わせ内では定額で、**長時間出力や高解像度出力でも追加料金はありません**。`ai.google.dev/gemini-api/docs/pricing`の公開料金によると、Googleの公式Veo 3.1は秒単位で課金されます。以下の割引は**8秒動画**で計算しています。
| モデル | APIYI価格 | Google公式 8s 1080p | Google公式 8s 4K |
| - | - | - | - |
| `veo-3.1-fast-generate-preview` | **\$0.3 / req** | \$0.96
**68.8%オフ** | \$2.40
**87.5%オフ** |
| `veo-3.1-generate-preview` | **\$1.2 / req** | \$3.20
**62.5%オフ** | \$4.80
**75.0%オフ** |
**課金に関する注意**:
* モデル名ごとに**リクエスト単位**で課金され、継続時間（4/6/8秒）、解像度（720p/1080p/4k）、または`input_reference`の有無に関係ありません — **4Kを選んでも720pと同じ料金です**
* 非同期モードでは、生成失敗 / コンテンツポリシーによる拒否 / 容量エラーのいずれも**課金されません**
* [Top-Up Promotions](/ja/faq/recharge-promotions) のチャージ特典ティアにより、実質コストはさらに下がります
* 4Kはレンダリングが4〜6倍遅く、ファイルは約10倍大きくなります — 日常利用では**1080pをデフォルト**にしてください
* Googleの公式4K料金は \$0.30/sec（fast）/ \$0.60/sec（standard）で、8秒あたり \$2.40 / \$4.80 です（出典: `ai.google.dev/gemini-api/docs/pricing`）
## グループ設定
VEO 3.1 Official は `Default` グループで動作し（1x）、**専用グループへの切り替えは不要**です。Token の課金モードは **Pay-per-request** または **Pay-as-you-go Priority** である必要があります。**純粋な Pay-as-you-go はサポートされていません**（必要に応じて [console](https://api.apiyi.com/token) で Token モードを切り替えてください）。
**導入時の手間が少ない**: VEO 3.1 Official は Default グループで動作し、Pay-per-request と Pay-as-you-go Priority の両方を受け付けます。専用グループの設定も不要です — **既存の Pay-per-request Token をそのまま使い、`base_url` を変更するだけの「ゼロ設定」導入に最適です**。
| 項目 | VEO 3.1 Official | 備考 |
| - | - | - |
| グループ | `Default` (1x) | 切り替え不要 |
| 課金方式 | Pay-per-request ✅ / Pay-as-you-go Priority ✅ / 純粋な Pay-as-you-go ❌ | 純粋な Pay-as-you-go は切り替えが必要です |
| Token 要件 | Pay-per-request または Pay-as-you-go Priority + Default グループ | 専用の Token は不要です |
| レート / 倍率 | 1.0x | 上記価格で直接精算されます |
## 技術仕様
| 項目 | `veo-3.1-fast-generate-preview` | `veo-3.1-generate-preview` |
| - | - | - |
| **価格** | \$0.3 / リクエスト | \$1.2 / リクエスト |
| **対応時間（秒、文字列）** | `"4"` / `"6"` / `"8"` | `"4"` / `"6"` / `"8"` |
| **対応解像度（`metadata.resolution`）** | `720p` / `1080p` / `4k` | `720p` / `1080p` / `4k` |
| **対応アスペクト比（`metadata.aspectRatio`）** | `16:9` / `9:16` | `16:9` / `9:16` |
| **音声** | ✅ 音声＋動画の同期 | ✅ |
| **画像から動画生成（input\_reference）** | ✅（参照画像1枚） | ✅（参照画像1枚） |
| **一般的な生成時間** | 720p：60〜90秒 · 1080p：80〜120秒 · 4K：5〜6分 | 同様 |
| **動画の保持期間** | 約24時間（`expires_at` を参照）— 速やかにダウンロードしてください | 同様 |
| **レスポンスフィールド** | `id` / `status` / `progress` / `created_at` / `completed_at`。完了時には `video_url` / `expires_at`、失敗時には `error` が追加される場合があります | 同様 |
**1080p / 4k 解像度では、`seconds` は `"8"` である必要があります** — `"4"` または `"6"` はアップストリームで拒絶されます。720p では3種類すべての時間がサポートされています。
## API エンドポイント
| エンドポイント | メソッド | 用途 | Content-Type |
| - | - | - | - |
| `/v1/videos` | POST | 動画生成タスクの送信（テキストから動画 / 画像から動画、統合エンドポイント） | `application/json` または `multipart/form-data` |
| `/v1/videos/{task_id}` | GET | タスクのステータスと進捗の確認 | — |
| `/v1/videos/{task_id}/content` | GET | **生成されたMP4のダウンロード（バイナリストリーム）** | — |
**⚠️ `/content` 経由でダウンロードしてください。`video_url` は一時的なプレビュー専用です**
動画を取得する標準的な方法は **`GET /v1/videos/{task_id}/content` であり、MP4バイナリストリームを返します**（`Authorization: Bearer` ヘッダーが必要です）。
留意事項：
* 完了時のレスポンスには `video_url`（認証不要の直接リンク）および `expires_at`（約24時間後）が含まれる**場合があります**が、**すべてのタスクで保証されているわけではない**ため、コード側で存在しない場合を処理する必要があります
* フロントエンドでは `/content` エンドポイントを `
**エンドポイントの選択**: プライマリは `api.apiyi.com` です。バックアップゲートウェイ `b.apiyi.com` も同一の動作をします。
## 主要パラメータ
**⚡ パラメータの完全リファレンス**: `model` / `prompt` / `seconds` / `size` / `metadata.*` の型、デフォルト値、制約を含む完全な表は、[テキストから動画 - パラメータリファレンス](/ja/api-capabilities/veo-3-1-official/text-to-video#parameter-reference) へ移動してください。このセクションでは、特に落とし穴になりやすい **3 つのパラメータ** のみを解説します。
### `seconds`（動画の長さ）
長さフィールドの名前は **`seconds`** であり（`duration` ではありません）、**文字列でなければなりません**（`"4"` / `"6"` / `"8"`）。数値を渡すと、次のようになります:
```
parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string
```
| 値 | 720p | 1080p | 4k |
| - | - | - | - |
| `"4"` | ✅ | ❌ | ❌ |
| `"6"` | ✅ | ❌ | ❌ |
| `"8"` | ✅ (デフォルト) | ✅ (必須) | ✅ (必須) |
**よくある落とし穴: フィールド名を `duration` にしても、黙って無視されます。** `duration` はこのチャンネルでは認識されないため → 破棄されるため → 長さはデフォルトの **4 秒** にフォールバックします:
* 720p（および 4 秒を許可する他のティア）では: **エラーにはなりませんが、4 秒しか取得できません**（これがまさに「8s を送ったのに 4s になった」ケースです）
* 1080p / 4k では: 4 秒は不正なので、`Resolution 1080p requires duration seconds to be 8 seconds, but got 4` でエラーになります
**正しい使い方: 値 `"8"`（文字列）を持つ `seconds` フィールドを送信してください。**
パラメータの優先順位: `metadata.durationSeconds > seconds > 8`
### `metadata.resolution`（解像度ティア）
| 値 | ピクセル（横向き） | ピクセル（縦向き） | 備考 |
| - | - | - | - |
| `720p` (デフォルト) | `1280x720` | `720x1280` | 3 つの長さすべて |
| `1080p` | `1920x1080` | `1080x1920` | **`seconds="8"` のみ** |
| `4k` | `3840x2160` | `2160x3840` | **`seconds="8"` のみ**、レンダリングは 4〜6 倍遅くなります |
パラメータの優先順位: `metadata.resolution > size > 720p`
### ⚠️ `generateAudio` を渡さないでください
Veo 3 / 3.1 は**標準で音声対応**ですが、`generateAudio` パラメータは**渡してはいけません**。上流側で `INVALID_ARGUMENT` によって拒否されます。音声を制御するには、**意図を prompt に書き込んでください**:
> 「海岸の灯台、夕暮れ時。波、遠くの海鳥、弱い風の音、映画のような雰囲気」
## ベストプラクティス
* **イテレーション／一括プレビュー** → `veo-3.1-fast-generate-preview` (\$0.3/リクエスト)
* **最終納品／4K** → `veo-3.1-generate-preview` (\$1.2/リクエスト)
* 両方を同じ prompt ＋ seed で実行し、目視で選択します
新しい prompt ごとに、まずは `seconds: "4"` から開始してカメラワークとスタイルを検証します（レンダリング時間：60〜90秒、\$0.3）。見た目が確定したら、8秒または1080pにスケールアップします。
公式チャンネルは**非同期のみ**です。POST で送信して `task_id` を取得 → `status: "completed"` になるまで8〜10秒ごとに `GET /v1/videos/{task_id}` をポーリング → `/content` からダウンロードします。**webhook はサポートされておらず、ポーリングのみ**となります。
* 720p / 1080p: ハードタイムアウト3分
* 4K: ハードタイムアウト10分
* POST 送信（multipart）: 最低30秒
`status` が `completed` に切り替わったら、**直ちに独自の OSS / CDN にダウンロードしてください**。リモート側のコピーは約24時間しか保持されないため、リモートの `task_id` に長期間依存しないでください。`/content` エンドポイントは、`status` が切り替わった直後に**時々 400 を返すことがあります**。その場合は4秒後に再試行してください（サンプルクライアントにはこの処理が組み込まれています）。同じエンドポイントからの `502` はプロバイダーがファイルを取得できないことを意味するため、再試行しても解決しません。
**`generateAudio` は渡さないでください**（`INVALID_ARGUMENT` が返されます）。環境音、セリフ、BGM については、prompt 内で「waves, distant seabirds, low wind sounds」のように指定してください。
同時実行数の上限は公開されていませんが、実際には10件の同時送信がすべて正常にキューに入りました。**本番環境では処理中のリクエスト（in-flight）数を10件以下に制限**し、429 / 5xx に対しては指数バックオフを適用することをお勧めします。
## エラーコードとリトライ
| ステータス / 症状 | 意味 | 推奨される対応 |
| - | - | - |
| `400` + `parse_request_failed` | `seconds` が数値でした | 文字列の `"4"` / `"6"` / `"8"` を使用してください |
| 4秒のみ / `... but got 4` | フィールド名が `duration` でした（通知なしで無視され、4秒にフォールバックします） | `seconds` を値 `"8"`（文字列）で使用してください |
| `INVALID_ARGUMENT` | 1080p/4Kで `generateAudio` または8秒以外を指定しました | `generateAudio` を削除し、HD/4Kには `seconds="8"` を設定してください |
| `401` | 無効な token | `Authorization: Bearer ` を確認し（余分な空白がないか）、キーがまだ有効であることを確認してください |
| `429` | レート制限 / 残高不足 | 指数バックオフでリトライ、チャージして再試行してください |
| `5xx` / `INTERNAL` | アップストリームの一時的なエラー | 同じシードで1〜2回リトライしてください（課金されません） |
| `GET /content` が400（`task status is IN_PROGRESS`）を返す | `status` が `completed` に切り替わった直後（最大約20秒間） | 最大約30秒間、4秒ごとにリトライしてください。curl には `-f --retry-all-errors` が必要です |
| `GET /content` が `502` を返す | プロバイダーがその動画ファイルを取得できません（現在は稀です。以下のFAQを参照） | **リトライしても解決しません**（数時間後でも502のままです）。`task_id` を控えてお問い合わせいただき、課金を確認してください。通常は新しいタスクとして再送信すれば機能します |
| タスク `failed` | 生成に失敗しました（通常はコンテンツ審査、アップストリームの容量不足、または生成されたファイルを取得できなかったことが原因です） | `error.message` を参照し、prompt を調整してリトライしてください。**タスクは課金されず、請求が発生した場合は自動的に返金されます** |
**推奨されるクライアント設定**:
* POST送信タイムアウト: **30秒**（multipartアップロードではさらに時間が必要な場合があります）
* ポーリング間隔: **8〜10秒**、最大待機時間 720p/1080p は **3分**、4K は **10分**
* 5xx および `failed` に対する指数バックオフリトライ（1〜2回の試行を推奨）
* `/content` から400が返された場合は、最大約30秒間、4秒ごとにリトライ
* **`/content` からの `400` と `502` は区別して処理**: `400` はリトライで解消されますが、`502` は解消されません — 2回試行した後に停止し、タスクを失敗としてマークして `task_id` を保持してください
## FAQ
**公式（本ページ）**：Google AI Studioの上流エンドポイントへの透過的なパススルーです。モデルIDはGoogle上流と一致し（`veo-3.1-generate-preview` / `veo-3.1-fast-generate-preview`）、リクエストあたり \$0.3 / \$1.2 で、非同期エンドポイントのみに対応しています。
**リバース**（既存の [VEO 3.1](/en/api-capabilities/veo/overview)）：Google Flowへのリバースエンジニアリングによるアクセスです。モデルIDは `veo-3.1-fast` / `veo-3.1` / `-fl` シリーズで、リクエストあたり \$0.15 からと安価であり、**ストリーミング同期**モードと非同期モードの両方に加え、**フレーム・トゥ・動画**（最初/最後のフレーム）にも対応しています。
完全な[公式 vs リバースの判定マトリクス](/ja/api-capabilities/veo-3-1-official/vs-veo-reverse)をご覧ください。両方のチャンネルは共存しているため、ビジネスニーズに合わせて選択してください。
**リクエストフィールドは `seconds` です**（文字列 `"4"` / `"6"` / `"8"`）。`duration` という名前にしても認識されず、サイレントに破棄されて長さはデフォルトの4秒にフォールバックします。これが「8秒で送信したのに4秒しか得られなかった」根本的な原因です。
なぜ文字列でなければならないかというと、バックエンドの Go 構造体がこのフィールド（内部名 `duration`）を `string` として宣言しているため、数値はデコーダー層で `parse_request_failed: cannot unmarshal number into Go struct field ... duration of type string` として拒否されます（そのエラー内の `duration` はバックエンドの内部フィールド名であり、リクエスト側は引き続き `seconds` を送信します）。**注意点：`seconds` を送信し、値をクォートしてください：`"4"` / `"6"` / `"8"`**。
Veo 3 / 3.1 は**ネイティブで音声に対応した**動画モデルですが、`generateAudio` パラメータは**渡してはいけません**（上流が `INVALID_ARGUMENT` を返します）。サウンドをコントロールするには、**prompt 内に意図を記述してください**：
> "Coastal lighthouse at dusk; waves, distant seabirds, low wind sounds, cinematic atmosphere"
* 同等のパラメータでは、**レンダリング時間はほぼ同じです**（720p 8秒の実測値：fast 83秒、standard 78秒）。**fast は高速という意味ではなく、より安価です**（\$0.3 vs \$1.2）
* デフォルトでは `veo-3.1-fast-generate-preview` を使用してください
* 最終納品時や、ディテールの忠実度・物理的な一貫性が重要な場合は `veo-3.1-generate-preview` に切り替えてください
* 本番環境でのA/Bテスト：同じ prompt ＋ seed で両方を実行し、視覚的に選定してください
**ほとんどのユースケースでは推奨されません**：
* リクエストごとの価格が同じなのは魅力的に見えます
* しかし、レンダリングが **4〜6倍遅くなります**（720p 80秒 → 4K 350秒）
* ファイルサイズが約10倍になります（720p 4MB → 4K 40MB）— 帯域幅とストレージのコストが跳ね上がります
* ほとんどの再生シナリオでは、視覚的に 1080p で十分です
**4K がどうしても必要な場合**：`veo-3.1-generate-preview` を使用し、`seconds="8"` を設定（必須）、クライアントのタイムアウトを10分以上に設定し、バックグラウンドの非同期タスクとして実行してください。
* **webhook はありません**。`GET /v1/videos/{task_id}` をポーリングするのみです
* 推奨ポーリング間隔：**8秒**（実測で十分であり、レート制限にも引っかかりません）
* 実測時間：720p / 1080p は 60〜115秒、4K は 5〜6分
* クライアントタイムアウト：720p/1080p は 3分、4K は 10分
**`400`：待つだけで解決します。** `status` が `completed` に切り替わった直後は、動画ファイルの同期がまだ完了していないため、`/v1/videos/{task_id}/content` を呼び出すと一時的に 400 が返されることがあります。このウィンドウは最大約20秒間続くため、**約30秒間、4秒ごとにリトライしてください**（サンプルのクライアントはすでにこの処理を行っています）。curl の場合、デフォルトでは `--retry` は 400 をリトライしない点に注意してください — `-f --retry-all-errors` を追加してください。
**`502`：リトライしても解決しません。** レスポンスボディは `{"error":{"message":"Upstream service returned status 502"}}` のようになります。生成自体は成功しており — `GET /v1/videos/{task_id}` は引き続き `status: "completed"` と `progress: 100` を返します — しかし**プロバイダーがその動画ファイルを取得できません**。弊社の実測では数時間後も 502 のままであるため、**自動的に回復することはありません**。これを無制限のリトライループとして記述しないでください。
対処法：
1. 最大2回リトライします。それでも 502 の場合は、そのタスクを失敗としてマークします
2. **`task_id` を控えてお問い合わせください** — その生成はすでに課金されているため、弊社側で確認して対応いたします
3. 新しいタスクとして再送信すれば通常は動画が生成されます。prompt を変更する必要はありません
**これは現在では稀です**：ほとんどのタスクは `completed` と報告される前に動画ファイルが取得可能かどうかがチェックされます。ファイルを取得できない場合、タスクは `status: "failed"`（理由は `error.message` に記載）となり、**料金は自動的に返金される**ため、取得できない動画に対して課金されることはなくなりました。ただし完全に排除できるわけではありません — **`GET /v1/videos/{task_id}` が `completed` を返すことは、動画が取得可能であることを意味しません。** これらは2つの独立した成功確認として扱ってください。
**可能な場合もありますが、一時的なものにすぎません**。完了したレスポンスには `video_url`（認証不要の直接リンク）と `expires_at`（完了から約24時間後のタイムスタンプ）が含まれている**場合があります**。これは**すべてのタスクで保証されているわけではなく**、有効期限が切れると機能しなくなるため、恒久的なアドレスとして配布しないでください。
**動画を取得する標準的な方法**：`status: "completed"` の後、`GET /v1/videos/{task_id}/content` を呼び出して **MP4 バイナリストリーム**を取得します（`Authorization: Bearer` ヘッダーが必要です）。これはすべてのタスクで機能します。
**標準的な本番パターン**：
1. タスク完了後すぐにバックエンドで MP4 をダウンロード → 独自の OSS / CDN にプッシュ
2. エンドユーザーには自社の CDN URL を提供
3. **フロントエンドの `
レスポンスの `expires_at` フィールドによると**約24時間**です（このフィールドがない場合は24時間と想定してください）。**完了後すぐにダウンロードしてローカルに保存することを強く推奨します** — リモートの `task_id` や `video_url` に長期的に依存しないでください。期限切れ後はどちらも利用できなくなります。
`progress` フィールドは大まかな粒度となっており、**いくつかの固定ステップ間でのみジャンプします**（0 / 10 / 30 / 50 / 100 など）。パーセンテージのプログレスバーには使用しないでください。スピナーを使用するか、ご自身で「経過時間 / 想定時間」を計算してください。
**いいえ**。**課金されるのは `status=completed` のタスクのみです**。`failed` / キャンセル / コンテンツポリシー違反による拒否 / パラメータエラーはすべて無料です。**実際の動画が出力されなければ課金されません**。
**バイト単位で同一にはなりません**。実測値：同一の prompt ＋ 同一の seed（`88888`）＋ 同一のパラメータで fast を2回実行した場合 — ファイルサイズは 9.81 MB vs 9.25 MB、md5 は完全に異なり、レンダリング時間も異なります。
**ただし seed は無意味ではありません**：同一 seed の出力は**まとまった傾向を示し**（5回実行テストでグループ内ファイルサイズのばらつきはわずか6%）、異なる seed では**体系的に変化します**（グループ間のばらつき +36.8%）。つまり：
* 「安定したルック」が欲しい場合 → seed を固定
* 「バリエーションを探索」したい場合 → prompt をいじるのではなく seed を変更
* 「完全な再現」が欲しい場合 → あきらめて mp4 を保存
**現時点ではどちらもサポートされていません**。画像・動画生成（Image-to-video）は1枚の画像のみを受け付け、フィールド名は `input_reference` に固定されており、**ファイルまたは Base64 のみで、リモート URL には対応していません**。
Google 上流の Veo 3.1 は複数参照 / 最初と最後のフレーム / 動画の延長をサポートしていますが、このチャンネルでは対応していません。**最初/最後のフレームを使用する場合は、[VEO 3.1 (リバース)](/en/api-capabilities/veo/overview) の `-fl` シリーズをご利用ください**。
10件の同時送信の実測では、すべてキューに入り成功し、拒否はありませんでした。正確な上限は公表されていません。**本番環境側では処理中のタスク（in-flight）を 10 以下に制限し**、429 / 5xx が発生した場合は指数バックオフを行うことを推奨します。
* 目に見えるウォーターマークはありません
* ただし、MP4 のメタデータ内に埋め込まれた **Google C2PA コンテンツクレデンシャル**（Google C2PA Media Services 発行、フォーマット `urn:c2pa:...`）が含まれています。エンドユーザーには見えませんが、**C2PA ツール（例：Adobe Content Authenticity）により「Veo によって生成された」ことを検証できます**
* 再配布シナリオではご注意ください。通常、動画の再生には影響しません
部分的に可能です。インターフェースは OpenAI の規約（`Bearer` 認証 ＋ `/v1/...`）に従っていますが、OpenAI 公式 SDK には **`videos.create` メソッドが公開されていません**（`/v1/videos` はカスタムパスです）。OpenAI SDK の低レベルな `client.post()` または直接の HTTP を使用してください。**生の HTTP が最もシンプルです** — [Text-to-Video Playground](/ja/api-capabilities/veo-3-1-official/text-to-video) のコードサンプルをご覧ください。
## 関連ドキュメント
* [Text-to-Video Playground](/ja/api-capabilities/veo-3-1-official/text-to-video) — `POST /v1/videos` (JSON) インタラクティブなデバッガー + 5言語のコードサンプル
* [Image-to-Video Playground](/ja/api-capabilities/veo-3-1-official/image-to-video) — `POST /v1/videos` (multipart) + `input_reference` の利用方法
* [Official vs Reverse の判断マトリクス](/ja/api-capabilities/veo-3-1-official/vs-veo-reverse) — [VEO 3.1 (Reverse)](/en/api-capabilities/veo/overview) との違い
* [チャージ特典](/ja/faq/recharge-promotions) — ボーナス階層と対象チャネル
* [API マニュアル](/ja/api-manual) — 一般的な呼び出し規約、タイムアウトと再試行のガイダンス
* Google 公式モデルページ: `ai.google.dev/gemini-api/docs/models/veo-3.1-generate-preview`
* Google の動画生成ドキュメント: `ai.google.dev/gemini-api/docs/video`
VEO 3.1 Official は APIYI の安定した公式リレーサービスであり、Google AI Studio への透過的なパススルーです。モデル ID、レスポンスフィールド、制約は Google の上流と完全に一致し、**また、このチャネルは Default グループで従量課金に対応しています** — 利用できる公式品質チャネルの中で最も導入しやすいものです。フィードバックはコンソールのサポートパネルから送信してください。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.