まずこちらをお読みください: 動画は Base64 インライン(リクエスト全体 ≤ 20 MB) または YouTube リンク(Gemini ネイティブ形式)でしか渡せません。一般公開の動画 URL(例:
https://example.com/demo.mp4)を渡すと Request contains an invalid argument が返ります —— これは Google が直接リンクを拒否しているためであり、APIYI 側のブロックではありません。下の「Video input methods」をご覧ください。Visual API テスト
動画をアップロードし、iCover のビジュアルテストツールで理解エンドポイントをテストします。
対応モデル
安定版の定番
gemini-2.5-pro(2M コンテキスト)と gemini-2.5-flash は引き続き利用できます。完全な料金はModels & Pricingをご覧ください。
動画入力方法
問題の多くはここから発生します。以下の表で、ご利用の入力方法がサポートされているか確認してください。クイックスタート: Base64 インライン(OpenAI互換形式)
最も一般的な方法は、ローカルの動画を読み込む → base64 エンコードする →image_url フィールドに渡す、という流れです。
<BASE64_VIDEO> を動画の base64 文字列に置き換えてください。大きなファイルでは、SDK に自動でエンコードさせる方法を推奨します):
YouTubeリンク(Gemini ネイティブ形式)
YouTubeリンクはダウンロード不要で、20 MB の制限も受けませんが、Gemini ネイティブ形式(google-genai SDK、endpoint https://api.apiyi.com)でのみ渡せます。
より多くのネイティブ形式の使い方(ストリーミング、thinking budget、関数呼び出しなど)については、Gemini Native Format をご覧ください。
高度なヒント
タイムスタンプ参照
モデルはデフォルトで1秒あたり1フレームでサンプリングし、音声トラックも理解するため、プロンプト内でMM:SS を使って直接、特定の場面を参照できます。これは純粋なプロンプト手法であり、どの入力方法でも使えます:
一般的なタスク向けのプロンプト案
同じ動画でも、プロンプトを変えるだけで異なる分析が可能です。コード変更は不要です:- コンテンツ要約: トピック、重要な場面、結論を3〜5文で要約する
- 教育的分析: 重要な概念、章ごとの構成、重要なタイムスタンプを抽出する
- 監視分析: 異常な行動、そこにいる人物・物体、発生時刻を特定する
- マーケティングレビュー: 訴求ポイントの見せ方、テンポ、ターゲット層との適合性を分析する
- 動作分析: 手順、姿勢の詳細、改善点を分解して確認する
技術メモ
- Sampling rate: デフォルトでは、モデルは 1秒あたり1フレーム(FPS) でサンプルし、音声トラックも理解します。
- Token usage: デフォルト解像度ではおおよそ 300 token/秒、低解像度ではおおよそ 100 token/秒 です。動画が長いほど必要な token も増えるため、見積もりはそれに応じて行ってください。
- Supported formats: mp4, mpeg, mov (quicktime), avi, webm, wmv, 3gpp, およびその他の一般的な形式。
FAQ
公開動画リンクで「リクエストに無効な引数が含まれています」/ 取得に失敗する
公開動画リンクで「リクエストに無効な引数が含まれています」/ 取得に失敗する
Google の動画理解は任意の公開直リンクを受け付けません(例:
https://example.com/video.mp4)し、Request contains an invalid argument を返します。これは APIYI や Nginx によるブロックではありません。次のいずれかを使用してください: ① Base64 インライン(≤20 MB); ② YouTube リンク(ネイティブ形式)。なぜ 20 MB の制限があるのですか?以前は動いていました
なぜ 20 MB の制限があるのですか?以前は動いていました
Base64 インラインの場合、リクエストボディ全体は常に 20 MB を上限としていました(Google の公式制限と一致します)。「以前は動いていた」のが公開直リンクを指しているなら、それは実際にはサポートされていた方法ではありませんでした。一部のケースでたまたまエラーにならなかっただけで、現在は仕様どおり拒否されます。
大きな動画をアップロードするために files.upload を使えますか?
大きな動画をアップロードするために files.upload を使えますか?
いいえ。Google の公式 Files API(
client.files.upload())は第三者にはサポートされていません。対応しているのは Google 自身の endpoint だけです。大きな動画には YouTube リンクを使うか、20 MB 未満に圧縮して Base64 を使用してください。20 MB を超える動画はどうすればよいですか?
20 MB を超える動画はどうすればよいですか?
方法は 2 つあります: ① YouTube にアップロードしてリンクを渡す(ネイティブ形式なので 20 MB 制限の対象外です); ② ffmpeg などのツールを使って、重要な区間をローカルで 20 MB 未満に圧縮または切り出してから、base64 エンコードする。
関連リソース
モデルと価格
すべての Gemini モデルと最新の価格を確認できます
Gemini ネイティブ形式
YouTube リンク、ストリーミング、推論バジェット、その他のネイティブな利用方法
視覚理解 API
画像コンテンツ認識とマルチモーダル解析
API リファレンス
完全な API 仕様とエンドポイントの詳細