- 汎用フォーマットは
video_urlです:{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,..."}}は Seed、Qwen、Kimi、MiniMax、Gemini で動作します。このページの以前のバージョンに記載されていた古いimage_url+data:video/mp4形式は Gemini でしか動作せず、それ以外のモデルではすべて 400 エラーが返されます。 - GPT、Grok、Claude、GLM、DeepSeek は動画入力を受け付けません。 GPT と GLM は動画を警告なしに破棄して 200 を返し、GPT はもっともらしい回答を捏造することさえあります。詳細は「動画に対応していないモデル」を参照してください。
- Gemini は通常の公開動画 URL を受け付けません:
Request contains an invalid argumentを返すか、動画が警告なしに破棄されて 200 を返し(prompt_tokensが数十程度にとどまる)、動画が見えないと答えたり、画面が真っ黒であると説明したりすることがあります。一方、Seed、Qwen、Kimi は公開 https URL を直接受け付けることができます。
ビジュアル API テスト
AIエージェントに統合を任せる
このプロンプトをコピーして Codex / Claude Code / Cursor に貼り付けてください
まずこのページのプレーンテキスト版を取得し(任意のドキュメントURLの末尾に .md を追加)、プロジェクト独自のスタックでコードを作成します。ユニバーサルな video_url 形式、Gemini のパブリックURL禁止ルールと20 MBの上限、そして動画が実際にモデルに届いたかを確認するための prompt_tokens のチェックは、すでに要件に組み込まれています。
このプロジェクトで動画理解の統合 / トラブルシューティングを行ってください:要約、シーンの説明、アクション分析、またはタイムスタンプの参照のために、動画をマルチモーダルモデルに送信します。
コードに触れる前にドキュメントを読んでください:このページのプレーンテキスト版を取得するには https://docs.apiyi.com/en/api-capabilities/video-understanding.md を取得してください。YouTubeリンクの場合は、gemini/native ページも読んでください …
- エンドポイントと形式:OpenAI互換の
POST https://api.apiyi.com/v1/chat/completionsを使用し、動画は常に … として渡してください
合計9つの要件があります。以下のボタンを使用してプロンプト全体をコピーしてください。
このプロンプトが防ぐトラブル
このプロンプトが防ぐトラブル
対応モデル
これらの結果は、2026-10-11 (UTC+8)に実施されたテストに基づいています。同一の10秒間のテストクリップ(2.5秒ごとに異なる数字と形状が表示されるもの)を各モデルに送信し、タイムスタンプ付きで数字を順番に列挙させました。動画を実際に見ずに生成された回答を排除するため、空白の画像をコントロール(対照群)として使用しました。gemini-3.7-flashおよびgemini-3.5-flashに加え、安定版の定番であるgemini-2.5-pro(2Mコンテキスト)とgemini-2.5-flashも引き続き利用可能です。3.8 Flashはテストにおいて、入力価格が半額でありながら3.5 Flashとまったく同じ動画tokens(10秒で約713)を消費しました。レイテンシーおよびtokenの数値は上記の10秒間・540pのテストクリップに適用されたものであり、より長い動画や高解像度の動画ではほぼ比例して増加します。実際のレイテンシーはエンドポイントやプロバイダー側のキューイングにも依存するため、同一のクリップでも2〜3倍変動することがあります。
動画非対応のモデル
動画入力方法
クイックスタート: 汎用フォーマット (video_url)
Seed、Qwen、Kimi、MiniMax、Gemini で利用できます。
<BASE64_VIDEO> を動画の base64 文字列に置き換えるか、url 全体を公開アドレスに置き換えてください):
Gemini固有のフォーマット
Base64インライン(レガシーなimage_url形式)
Geminiは上記のvideo_url形式と下記のimage_url形式の両方を受け付けるため、既存のコードはそのまま動作します。新規コードでは、モデルを自由に変更できるようvideo_urlを使用してください。
Base64インライン(Geminiネイティブフォーマット)
プロジェクトですでにGoogle公式のgoogle-genai SDKを使用している場合、OpenAI互換フォーマットに切り替える必要はありません。base_urlをhttps://api.apiyi.comに向け、動画をPart.from_bytesでインライン化します。上記と同様に、リクエストボディ全体を20 MB未満に抑える必要があります。
-d @req.jsonで送信してください。
YouTubeリンク(Geminiネイティブフォーマット)
YouTubeリンクはダウンロードが不要で、20 MBの制限も受けませんが、Geminiネイティブフォーマット経由(google-genai SDK、エンドポイントhttps://api.apiyi.com)でのみ動作します。
動画をサポートしていないモデル:フレームを画像として扱う
GPTやGrokなどの画像専用モデルでは、ローカルで一定の間隔でフレームを抽出し、複数の画像として送信します。テストでは、gpt-6-sol、gpt-6-luna、gpt-5.6-terra、grok-4.7、grok-4.5のすべてが4つのフレームから内容と順序を正しく説明できました。トレードオフとして、音声およびフレーム間の動きが失われるため、タイミングはプロンプト内でご自身で指定する必要があります。
高度なヒント
タイムスタンプの参照
MM:SS を使用して prompt 内でセグメントを直接参照します。これは純粋なプロンプティング技術であり、動画をサポートするすべてのモデルで動作します:
回答が信頼できなくなる2つのケース
① 動画がモデルに届いていない場合:レスポンス内のusage.prompt_tokens を確認してください。10秒のクリップは、Seed / Qwen では約5,000 tokens、Gemini では約700 tokens です。わずか数十 tokens しかない場合、動画はドロップされています(これは GPT や GLM、および公開 URL を指定された場合の Gemini で発生します)。そのため回答は信頼できません。モデルは必ずしも「何も見えない」と言うわけではありません。公開 URL が指定された場合、Gemini は欠落した動画を「完全に真っ黒な画面」と描写し、GPT は存在しない内容をでっち上げます。
② 入力が誤っており、prompt が内容を前提としている場合:たとえば、誤ったファイルが送信された、動画のデコード結果が黒またはグレーの画面になった、統合時にプレースホルダー画像が使用された場合などです。この場合、prompt_tokens は完全に正常に見えるため、token 数では検知できません。
一般的なタスク向けの prompt アイデア
コードを変更することなく、prompt を変更するだけで、同一の動画からまったく異なる分析を引き出すことができます:- コンテンツ要約:トピック、主要なシーン、要点を3〜5文で要約します
- レッスン分析:主要な概念、チャプター構成、重要なタイムスタンプを抽出します
- 監視映像レビュー:異常な行動、出現する人物/物体、およびそれらが出現した時刻をフラグ付けします
- マーケティングレビュー:製品のセールスポイントの見せ方、テンポ、オーディエンスへの適合度を評価します
- 動作分析:動作のステップ、姿勢のポイント、改善点を分解・分析します
技術的な注意事項
- Gemini: デフォルトで毎秒1フレームをサンプリングし、音声トラックも処理します。Gemini 3.xはデフォルトで低解像度としてフレームをカウントし、弊社のテストでは毎秒約70 tokensでした。
- Seed / Qwen: 弊社のテスト(540p動画)では毎秒約500 tokensでした。Seedのサンプリングは
fpsで調整可能です。 - Kimi K3: 弊社のテストでは毎秒約1,400 tokensであったため、長時間の動画では大幅にコストが高くなります。
- サポート形式: mp4、mov、webmなどの一般的な形式に対応しています。H.264のmp4に変換すると最も高い互換性が得られます。
よくある質問
GPT、Grok、Claudeは動画を理解できますか?
GPT、Grok、Claudeは動画を理解できますか?
動画理解に対応している中国製モデルはどれですか?
動画理解に対応している中国製モデルはどれですか?
seed-2-0-pro-260328、dola-seed-2-1-turbo-260628、seed-2-0-lite-260428、seed-2-0-mini-260428、seed-1-8-251228)、Qwenのqwen3.8-max、qwen3.8-flash、qwen3-vl-plus、qwen3.5-omni-plus、およびkimi-k3です。MiniMax-M3はコンテンツを認識しますが、タイムスタンプを誤認します。glm-5.3とdeepseek-v4-flash-vision-expは動画に対応していません。モデルを切り替えると、同じコードで400が返されるのはなぜですか?
モデルを切り替えると、同じコードで400が返されるのはなぜですか?
image_url + data:video/mp4の形式を使用している可能性が最も高く、これはGeminiのみが受け付けます。{"type": "video_url", "video_url": {"url": ...}}に切り替えることで、各プロバイダー間で動作するようになります。Geminiが動画に含まれていない内容を説明したのはなぜですか?
Geminiが動画に含まれていない内容を説明したのはなぜですか?
公開動画のURLで「Request contains an invalid argument / fetch failed」が返されます
公開動画のURLで「Request contains an invalid argument / fetch failed」が返されます
https://example.com/video.mp4)。これはAPIYIによるブロックではありません。Geminiでは、インラインのbase64(20 MB未満)またはYouTubeリンクを代わりに使用してください。あるいは、公開URLを直接取得できるSeed / Qwenに切り替えてください。/v1/chat/completionsでは必ずしもエラーになるわけではなく、モデルが黒画面しか見えないと主張して200を返す場合があります。その場合、prompt_tokensはわずか数十個となり、結果は使用できません。なぜGeminiはリクエストを20 MBに制限しているのですか?以前は動作していました。
なぜGeminiはリクエストを20 MBに制限しているのですか?以前は動作していました。
大きな動画に対してfiles.uploadを使用できますか?
大きな動画に対してfiles.uploadを使用できますか?
client.files.upload())はサードパーティのエンドポイントではサポートされていません(Google独自のエンドポイントでのみサポートされています)。大きな動画の場合は、YouTubeリンクを使用するか、base64用に20 MB未満に圧縮するか、公開URLを使用してSeed / Qwenに切り替えてください。20 MBを超える動画はどうすればよいですか?
20 MBを超える動画はどうすればよいですか?