メインコンテンツへスキップ
APIYI 上の複数のモデルファミリーは動画を「視聴」できます。1つの prompt だけで、モデルはシーン、アクション、画面上のテキストを認識し、タイムスタンプによって重要な瞬間を参照できます。Gemini のほか、Seed(Doubao)ファミリー全体、Qwen のビジョンおよび omni モデル、Kimi K3 のすべてが当社のテストに合格しました。このページでは、サポート対象リスト、汎用リクエストフォーマット、およびつまずきやすい制限事項について解説します。
まず以下の3点をご確認ください:
  1. 汎用フォーマットは video_url です: {"type": "video_url", "video_url": {"url": "data:video/mp4;base64,..."}} は Seed、Qwen、Kimi、MiniMax、Gemini で動作します。このページの以前のバージョンに記載されていた古い image_url + data:video/mp4 形式は Gemini でしか動作せず、それ以外のモデルではすべて 400 エラーが返されます。
  2. GPT、Grok、Claude、GLM、DeepSeek は動画入力を受け付けません。 GPT と GLM は動画を警告なしに破棄して 200 を返し、GPT はもっともらしい回答を捏造することさえあります。詳細は「動画に対応していないモデル」を参照してください。
  3. Gemini は通常の公開動画 URL を受け付けません: Request contains an invalid argument を返すか、動画が警告なしに破棄されて 200 を返し(prompt_tokens が数十程度にとどまる)、動画が見えないと答えたり、画面が真っ黒であると説明したりすることがあります。一方、Seed、Qwen、Kimi は公開 https URL を直接受け付けることができます。

ビジュアル API テスト

iCover ビジュアルテストツールで動画をアップロードし、理解エンドポイントをテストします。

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 ページも読んでください …

  1. エンドポイントと形式: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倍変動することがあります。
モデルの価格は公式サイトに準拠しており、公式サイトの変更に伴って変動する場合があります。上記の表は参考用です。トップナビゲーションのモデル価格タブが正式な情報となります:モデル価格。

動画非対応のモデル

GPTは動画が破棄された後に回答を捏造する可能性があります:弊社のテストでは、gpt-6-solは3回のテストすべてで動画内に存在しない数字の並びを創作し、ロンドンの街頭風景を「空気注入式の浮き具があるプール」と説明しました。これらのモデルを使用する必要がある場合は、以下の「フレームを画像として渡す」アプローチに切り替えてください。

動画入力方法

Geminiの20 MB制限: Base64を使用する場合、リクエストボディ全体(エンコードされた動画を含む)を20 MB未満に抑える必要があります。より大きな動画の場合は、① YouTubeリンクを使用する、② エンコード前にローカルで動画を20 MB未満に圧縮またはトリミングする、③ Seed / Qwenに切り替えて公開URLを直接渡す、のいずれかを行ってください。
プロバイダーがURLを取得できる必要があります: 動画はモデルプロバイダーによってダウンロードされるため、プロバイダー側からアドレスにアクセスできる必要があります。弊社のテストでは、Volcengineオブジェクトストレージ上のURLはSeed、Qwen、Kimi、MiniMaxで動作しましたが、Google Cloud StorageのURLはSeedで403を返しました。不明な場合は、まずBase64での動作を確認してから、URLに切り替えてください。

クイックスタート: 汎用フォーマット (video_url)

Seed、Qwen、Kimi、MiniMax、Gemini で利用できます。
同等の curl 呼び出し(<BASE64_VIDEO> を動画の base64 文字列に置き換えるか、url 全体を公開アドレスに置き換えてください):
Seed ではサンプリングレートの調整が可能です: "fps": 2 を video_url 内に追加することで、速い動きをより詳細に確認できます(テストでは、10秒のクリップで入力 tokens が約4,900から約6,200に増加しました)。Qwen と Kimi はこのフィールドを無視します。

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未満に抑える必要があります。
RESTでの同等操作:Base64文字列は長いため、コマンドライン引数に直接貼り付けず、まずJSONファイルに書き出してから-d @req.jsonで送信してください。
ネイティブフォーマットを使用すると、動画がモデルに届いたかどうかを簡単に確認できます:レスポンス内のusageMetadata.promptTokensDetailsによって入力がモダリティごとに分割されます。当社の10秒のテスト動画ではVIDEOが660、これに加えていくつかのTEXT tokensが返され、OpenAI互換フォーマットと同じ合計値になりました。VIDEOのエントリがない場合、動画は受信されていません。

YouTubeリンク(Geminiネイティブフォーマット)

YouTubeリンクはダウンロードが不要で、20 MBの制限も受けませんが、Geminiネイティブフォーマット経由(google-genai SDK、エンドポイントhttps://api.apiyi.com)でのみ動作します。
ネイティブフォーマットのその他の機能(ストリーミング、思考バジェット、関数呼び出しなど)については、Geminiネイティブフォーマットを参照してください。

動画をサポートしていないモデル:フレームを画像として扱う

GPTやGrokなどの画像専用モデルでは、ローカルで一定の間隔でフレームを抽出し、複数の画像として送信します。テストでは、gpt-6-sol、gpt-6-luna、gpt-5.6-terra、grok-4.7、grok-4.5のすべてが4つのフレームから内容と順序を正しく説明できました。トレードオフとして、音声およびフレーム間の動きが失われるため、タイミングはプロンプト内でご自身で指定する必要があります。

高度なヒント

タイムスタンプの参照

MM:SS を使用して prompt 内でセグメントを直接参照します。これは純粋なプロンプティング技術であり、動画をサポートするすべてのモデルで動作します:
正確なタイムスタンプが重要な場合は、Seed または Qwen を優先してください。弊社のテストでは、MiniMax-M3 のタイムスタンプは信頼性に欠けていました。

回答が信頼できなくなる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 数では検知できません。
**Gemini モデルは、ケース②において質問に同調し、回答をでっち上げる傾向があります。**弊社のテストでは、動画を空白の画像に置き換えて検証しました:
  • 中立的に質問した場合(「受け取った内容を説明してください」)、Gemini 3.8 Flash / 3.5 Flash / 3.1 Pro / 3.1 Flash Lite は全12回の実行すべてで空白の画像であると正しく回答しました — 画像理解自体には問題ありません。
  • しかし、質問が内容を前提としたものになると(「動画に表示されている数字を順番に挙げてください」や、「数字はありますか?なければ『ない』と答えてください」など)、3.5 Flash / 3.1 Pro / 3.1 Flash Lite は18回中12回で存在しない数字をでっち上げました。
  • より新しい gemini-3.8-flash は明らかに改善されていますが、完全に解決されたわけではありません。同様の誘導的な質問に対して、7回中2回で依然として回答をでっち上げました。
  • 同じ質問をしたところ、Seed、Qwen、Kimi はすべて、数字は見えない/存在しないと正しく回答しました。
実際の動画の認識には影響ありません。入力を直接制御できないバッチパイプラインでは、まず中立的な質問をしてモデルに見えている内容を説明させ、入力が正しいことを確認した上で具体的な質問をするか、または Seed / Qwen を使用してください。

一般的なタスク向けの 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に変換すると最も高い互換性が得られます。

よくある質問

いいえ。ClaudeとGrokはエラーを直接返します。GPTのチャットエンドポイントは**動画を暗黙的に無視(ドロップ)**して200を返し続けるため、モデルが回答を捏造する可能性があります。これらのモデルが必要な場合は、まずフレームを抽出して画像として送信してください。「動画非対応モデル:フレームを画像として送信」を参照してください。
弊社のテストに合格したもの:Seedファミリー全体(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は動画に対応していません。
レガシーなimage_url + data:video/mp4の形式を使用している可能性が最も高く、これはGeminiのみが受け付けます。{"type": "video_url", "video_url": {"url": ...}}に切り替えることで、各プロバイダー間で動作するようになります。
まず、入力自体に問題がないか確認してください(黒画面、空白フレーム、誤ったファイルなどではないか)。弊社のテストでは、入力が誤っており、質問が動画の内容を前提としている場合、Geminiは質問に合わせた回答を捏造する傾向がありました。トラブルシューティングを行うには、「受信した内容を説明してください」のような中立的なpromptに切り替え、動画が正しく説明されているか確認してください。詳細は「回答が信頼できない2つのケース」を参照してください。
Geminiは任意の公開URLを受け付けません(例:https://example.com/video.mp4)。これはAPIYIによるブロックではありません。Geminiでは、インラインのbase64(20 MB未満)またはYouTubeリンクを代わりに使用してください。あるいは、公開URLを直接取得できるSeed / Qwenに切り替えてください。/v1/chat/completionsでは必ずしもエラーになるわけではなく、モデルが黒画面しか見えないと主張して200を返す場合があります。その場合、prompt_tokensはわずか数十個となり、結果は使用できません。
インラインのbase64を使用する場合、Geminiは常にリクエストボディ全体を20 MBに制限しています(Googleの公式制限に準拠)。「以前は動作していた」ものが公開URLであった場合、それは本来サポートされている方法ではありませんでした。一部のケースでたまたまエラーにならなかっただけであり、現在は明示的に拒否されます。
いいえ。Geminiの公式Files API(client.files.upload())はサードパーティのエンドポイントではサポートされていません(Google独自のエンドポイントでのみサポートされています)。大きな動画の場合は、YouTubeリンクを使用するか、base64用に20 MB未満に圧縮するか、公開URLを使用してSeed / Qwenに切り替えてください。
3つの選択肢があります:① YouTubeにアップロードしてリンクを渡す(Geminiネイティブ形式)、② ffmpegなどのツールを使用してキーセグメントを20 MB未満に圧縮またはトリミングし、base64としてエンコードする、③ 一般公開アクセス可能なオブジェクトストレージで動画をホストし、そのURLをSeed / Qwenに渡す。

関連リソース

モデル料金

全モデルと最新の料金情報

Gemini ネイティブフォーマット

YouTubeリンク、ストリーミング、thinking budget、その他のネイティブ機能

画像理解API

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

Qwen3.8-Max

ネイティブな画像および動画入力に対応したQwenフラグシップモデル