アプリの紹介動画を Gemini に読ませる処理を見直していた夜、フォーラムで一つのスレッドに目が止まりました。約 23 秒の MP4 を agentic モードで解析させたところ、数分待たされたあとに HTTP 500 が返り、本文には「high demand」とあった、という投稿です。
動画解析が重い処理であることは知っておりました。それでも、23 秒で数分待って落ちるという話には、少し違和感がありました。ここでは、その報告を整理し、公式ドキュメントの使い分けと照らして、失敗したときに「待つ」「分ける」「落とす」のどれを選ぶかを先に決めておく方法をお伝えします。
最初にお伝えしておくと、私自身はこの失敗を手元で再現しておりません。報告の部分はスレッドに書かれていることの整理で、コードは API を呼ばない模擬の失敗で動作を確かめたものです。
報告されていること
フォーラムのスレッド（2026 年 9 月 17 日投稿）には、次のことが書かれています。
2026 年 9 月 16 日に、約 23 秒の MP4 を Files API にあげ、processing を agentic にして /v1beta/interactions へ送りました。gemini-3.8-flash で 2 回、gemini-3.7-flash で 1 回、いずれも数分後に HTTP 500 で終わり、解析結果は得られていません。認証とアップロードまでは通っています。
保存されていた 3.7 側のエラー本文は、「現在 high demand で、需要の急増は通常一時的です。後ほどお試しください」という趣旨のものでした。投稿者は、全員に起きているのかは分からないとも書いています。
運営側からは 9 月 18 日に、プロジェクト ID かリクエスト ID とプロンプトをダイレクトメッセージで送ってほしい、という返信がありました。原因の特定、既知の障害としての認定、回避策や推奨設定は、スレッドの範囲では示されていません。関連として、9 月 8 日付で「agentic の処理呼び出しが 23 回を数えたあとに HTTP 200 から api_error になる」という別スレッドも並んでいました。
つまり、確実に言えるのは「そう報告されている」ところまでで、混雑なのか、特定の入力による不具合なのかは、まだ分かりません。
公式が書いている使い分け
動画理解のドキュメントを読み直して、気づいたことが一つあります。
agentic は、5〜10 分を超えるような長い動画や、特定の場面を探す問いに向く方式だと説明されています。一方で、短いクリップや広い問いでは、ナビゲーションの推論とツール往復のぶん、最初のトークンまでの時間と総トークン数が増えることがある、とも書かれています。5 分に満たない動画や、全体の要約、遅延に敏感な処理、フレーム単位の精度が欲しい場合は、静的モードが向くとされています。
報告された動画は約 23 秒です。公式の使い分けに照らすと、agentic を選ぶ理由が薄い入力だったことになります。これが失敗の原因だと言うつもりはありません。混雑が原因なら、静的モードでも落ちたかもしれないのです。ただ、「待てば通るかもしれない」と考える前に、そもそもそのモードが必要だったのかを確かめる価値はあります。
もう一つ、同じページには、長い処理にはストリーミングかバックグラウンド実行を使うこと、同期リクエストが高負荷時のバックエンド再試行にぶつかると、401 Unauthorized やタイムアウトになることがある、と書かれています。同期で投げて数分待たされたあとに 500 や 401 を受け取る形は、この注意書きとも重なります。
三つの分かれ道を先に決める
失敗が出てから考えると、人は「もう一度投げる」を選びがちで、待ち時間だけが積み上がります。そこで、次の表のように、状況ごとの一手を先に決めています。
| 状況 | 最初の一手 | 理由 |
|---|---|---|
| 5 分未満の動画で agentic を使っている | 静的モードに切り替える | 公式の使い分けで、静的が向く長さだからです |
| 長い動画で agentic が 500・503 になる | 待ち時間を倍にして 1〜2 回だけ再試行する | 混雑なら一時的なことが多く、すぐ叩き直しても同じ場所に当たるためです |
| agentic が 2 回続けて失敗した | 区間を切って静的モードで読む | クリップ指定は静的モードでだけ使えます |
| 400 番台（401 を除く） | 再試行せず入力を直す | 待っても直らない種類の失敗です |
401 だけは例外として扱っています。上で触れたとおり、同期呼び出しの高負荷時に 401 が返ることがあるため、同期で投げていたなら、まず background=True に変えて様子を見ます。
失敗の種類で次の一手を変える Python
次のスクリプトは、最初のモードを長さから決め、500・503・504 のときだけ待ち、agentic が 2 回続けて落ちたら静的に切り替えます。call(mode) の中身は、自分の API 呼び出しに差し替えてください。
#!/usr/bin/env python3
"""動画理解の失敗を見て、次の一手（待つ・静的に落とす・諦める）を決める。"""
import random
import time
RETRYABLE = {500, 503, 504}
AGENTIC_MIN_SECONDS = 300 # 公式の目安: 約5分未満は静的が向く
def choose_mode(duration_s, needs_frame_precision=False):
"""最初に使うモードを決める。短い動画やフレーム精度が要る場合は静的。"""
if needs_frame_precision or duration_s < AGENTIC_MIN_SECONDS:
return "static"
return "agentic"
def run_with_fallback(call, duration_s, needs_frame_precision=False,
max_wait_s=600, sleep=time.sleep):
"""call(mode) がテキストを返す関数。失敗の種類で次の一手を変える。"""
mode = choose_mode(duration_s, needs_frame_precision)
log, waited, delay = [], 0, 20
while True:
try:
return mode, call(mode), log
except Exception as e:
code = getattr(e, "code", None)
log.append((mode, code))
if code not in RETRYABLE:
raise # 認証や入力の誤りは待っても直らない
agentic_fails = sum(1 for m, _ in log if m == "agentic")
if mode == "agentic" and agentic_fails >= 2:
mode = "static" # 同じ道を三度叩かない
continue
if waited + delay > max_wait_s:
raise
sleep(delay + random.uniform(0, delay / 4))
waited += delay
delay *= 2call を差し替えやすいようにしたのは、再試行の方針と API の呼び出しを切り離しておきたかったからです。方針だけを模擬の失敗で試せば、実際の API を叩かずに分かれ道の動きを確かめられます。
模擬の失敗で動かしてみた
agentic だと必ず 500、静的だと成功する偽の呼び出しを作り、15 分（900 秒）の動画として渡しました。出力は次のとおりです。
('static', [('agentic', 500), ('agentic', 500)]) 待機回数 1
static agentic static
401 はそのまま送出: HTTP 401agentic が 2 回落ちたところで静的に切り替わり、待機は 1 回だけで済みました。23 秒の動画は最初から静的、15 分の動画は agentic、フレーム精度が必要な場合は 15 分でも静的、という選び方も確かめています。401 は再試行せずに送出されます。ここまでは、あくまで方針の確認です。実際の混雑時に、この順番がうまく働くかどうかは、私の手元ではまだ確かめておりません。
落とし穴
静的への切り替えは、長い動画ではそのまま使えません。静的モードの目安は 1 秒あたり約 100 トークン（低解像度）で、長時間の動画を丸ごと渡すとトークン量が大きくなります。長い動画で agentic が通らないときは、start_offset と end_offset で区間を切って渡すほうが現実的です。クリップ指定と fps の指定は、静的モードでだけ使えます。
もう一つは、運営への問い合わせに備えて、失敗のたびにリクエスト ID と日時、モード名を残しておくことです。スレッドでも、最初に求められたのはそれでした。再試行を重ねても、記録が残っていなければ、あとで原因を一緒に探せません。
agentic が実際に動いたかどうかは、応答の steps に processing_call と processing_result があるかで確認できます。成功したはずなのに安く済みすぎている、と感じたときの手がかりになります。
関連して、再試行してよい失敗と人が出る失敗の分け方は、429 の再試行設計に書きました。動画の長さと fps の選び方は、タイムスタンプ付きの動画理解で扱っております。
次にやること
まず、ご自分の動画解析の呼び出しを開いて、agentic を指定している箇所が、本当に 5 分を超える動画にだけ使われているかを確かめてみてください。短い動画に付いていたなら、静的に戻すだけで、待ち時間も失敗も減るかもしれません。
待つかどうかを決める前に、そのモードが要るのかを確かめると決めています。 この線引きを、私はいまも守るようにしています。