Skip to main content
APIYI は Gemini のマルチモーダルモデルを通じて動画理解を提供します。1 つの prompt だけで、モデルは動画内のシーン、アクション、画面上のテキスト、音声を「視聴」し、タイムスタンプ付きで重要な瞬間を参照できます。このページでは、対応モデル、実際に動作する動画入力方法、そしてつまずきやすい制限について説明します。
まずこちらをお読みください: 動画は 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をご覧ください。

動画入力方法

問題の多くはここから発生します。以下の表で、ご利用の入力方法がサポートされているか確認してください。
20 MB の制限: Base64 を使用する場合、エンコードされた動画を含むリクエスト本文全体は 20 MB 未満に収める必要があります。20 MB を超える動画の場合の選択肢は、① YouTube リンクを使う、② base64 エンコードする前に動画をローカルで圧縮 / 切り出して 20 MB 未満にする、の 2 つだけです。

クイックスタート: Base64 インライン(OpenAI互換形式)

最も一般的な方法は、ローカルの動画を読み込む → base64 エンコードする → image_url フィールドに渡す、という流れです。
同等の curl(<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 リンク(ネイティブ形式)。
Base64 インラインの場合、リクエストボディ全体は常に 20 MB を上限としていました(Google の公式制限と一致します)。「以前は動いていた」のが公開直リンクを指しているなら、それは実際にはサポートされていた方法ではありませんでした。一部のケースでたまたまエラーにならなかっただけで、現在は仕様どおり拒否されます。
いいえ。Google の公式 Files API(client.files.upload())は第三者にはサポートされていません。対応しているのは Google 自身の endpoint だけです。大きな動画には YouTube リンクを使うか、20 MB 未満に圧縮して Base64 を使用してください。
方法は 2 つあります: ① YouTube にアップロードしてリンクを渡す(ネイティブ形式なので 20 MB 制限の対象外です); ② ffmpeg などのツールを使って、重要な区間をローカルで 20 MB 未満に圧縮または切り出してから、base64 エンコードする。

関連リソース

モデルと価格

すべての Gemini モデルと最新の価格を確認できます

Gemini ネイティブ形式

YouTube リンク、ストリーミング、推論バジェット、その他のネイティブな利用方法

視覚理解 API

画像コンテンツ認識とマルチモーダル解析

API リファレンス

完全な API 仕様とエンドポイントの詳細