API タイムアウトを回避するには？

簡潔な回答

タイムアウト問題の90%をカバーする3つの黄金ルール:

同期型の画像生成エンドポイントには 360 秒のタイムアウトを設定します。 画像生成には非同期タスク ID がないため、早く切断すると課金はされるのに画像は取得できません。
推論モデルには十分な時間を与えます。 gemini-3.1-pro-preview、gpt-5.6-sol、gpt-5.5-pro は、stream するかどうかに関係なく、数分かかることがあります。
長時間のリクエストを CDN ノード経由で実行しないでください。 api-cf.apiyi.com は Cloudflare の背後にあり、約 100 秒を超えると 524 を返します。高速なテキスト呼び出しにのみ適しています。

別件ですが、特定のモデルが 429（同時実行数不足）を返し続ける場合は、サポートに連絡してクォータを確認してもらってください。

タイムアウトチートシート

シナリオ	推奨タイムアウト	推奨ノード	備考
通常のテキストチャット（非推論）	60〜120秒	任意のノード	通常は数秒で応答
推論モデル（思考 / 推論）	300〜600秒	`api.apiyi.com` / `b.apiyi.com`	ストリーミングの有無にかかわらず低速
長文テキスト出力（1万語以上）	300秒以上	`api.apiyi.com` / `b.apiyi.com`	❌ CDNノードは不可
画像生成 / 編集	基準 360秒	`api.apiyi.com` / `b.apiyi.com`	❌ CDNノードは不可
4K画像、複数画像参照	600秒	同上	画像のベストプラクティスを参照

タイムアウトしたリクエストも課金されますクライアントが切断された後も、サーバーおよび上流プロバイダーは処理を最後まで完了し、そのリクエストには通常通り課金されます。言い換えれば、タイムアウトを短く設定しすぎると、料金を支払ったのに何も得られないことになります。成功寸前のリクエストがクライアント側によって中断されてしまわないよう、あらかじめ余裕を持った安全な上限値を設定してください。

4つの重要ポイントの詳細

① 同期画像エンドポイント：タイムアウトを360秒に設定

APIYIのすべての画像モデルは同期型です。リクエストを送信して接続を維持すると、レスポンスボディで結果が返されます。非同期タスクIDやポーリング用のエンドポイントは存在しないため、接続が切断されると結果は失われます。デフォルト値が問題となる理由：主要なHTTPクライアントのデフォルト値は30〜60秒ですが、画像生成は本質的に長時間の処理を伴うリクエストです。

GPT-Image-2で2K/4Kかつhigh品質の場合、実際には3〜5分かかります
Nano Bananaの4K生成は約50秒から始まり、ピーク時にはさらに長くかかります
複数画像を参照するタスクは多くの場合5分を超えます

推奨事項：モデルのレイテンシーが不明な場合は、ベースラインとして360秒を設定してください。4Kや複数画像参照などの重いタスクには600秒を確保してください。モデルごとの値については、画像APIのベストプラクティスを参照してください。

ログ上では画像が30秒で完了したと表示されているにもかかわらず、クライアントが5分間待機することが稀にあります。これは、ログの所要時間がゲートウェイの処理完了時点までしか計測されないのに対し、クライアントはボディの受信完了と接続の完了シグナルを待つためです。タイムアウトを延長することが常に有効とは限りません。ダウンロードが遅いケースには有効ですが、データがすでに完了していて完了シグナルのみが欠落している場合には効果がありません。ログでは完了と表示されているのにクライアント側で何も受信できないに従って一度計測した上で判断してください。

② 推論／長文出力モデル：非ストリーミングでは維持不可、ストリーミングを使用

通常のテキストモデルは数秒で応答するため、テキスト呼び出しではタイムアウトの調整が不要だと思われがちです。しかし、推論モデルや、1回の呼び出しで数万文字を出力するようなワークロードは例外です：

gemini-3.1-pro-preview
gpt-5.6-sol
gpt-5.5-pro（高価格かつ低速）
claude-opus-5およびディープシンキング／高エフォートを実行するその他のモデル
長文出力タスク：ドラマの脚本、小説、長文翻訳、大規模なコード生成

これらの呼び出しは長時間推論を行った後、トークンごとに長い本文を出力するため、合計レイテンシーが10分以上になることも珍しくありません。重要ポイント：非ストリーミングでは接続を維持できませんが、適切な読み取りタイムアウトを設定したストリーミングを使用することで解決できます。非ストリーミングでは生成全体がバッファリングされてから一括送信されるため、読み取りタイムアウトが生成全体の時間と競合し、わずかな不具合でも切断されてしまいます。ストリーミングを使用すると、最初のバイトが数秒以内に届き、その後は数十秒ごとにデータイベントが到着します（推論中の無音ギャップの実測最大値は約42秒で、合間にキープアライブpingが挟まれます）。そのため、読み取りタイムアウトは合計時間ではなく、イベント間のギャップのみをカバーすれば十分です。推奨事項：

長文出力にはストリーミングを推奨します（stream=True）。読み取りタイムアウトは生成全体をカバーする巨大な値ではなく、イベント間のギャップに合わせた90〜120秒に設定してください。
非ストリーミングを維持する必要がある場合は、タイムアウトを300〜600秒に設定し、不安定さを許容してください。実行時間が長くなるほど、結果が届く前に切断される可能性が高くなります。
許容した時間に合わせて思考ティア（reasoning_effort / thinking）を調整してください。上位のティアほど余裕を持った時間が必要です。

長文出力の完全なレシピ（ストリーミングコード、max_tokens、stop_reason、リトライ）については、長文出力の実践を参照してください。

③ Base URLの選択：CDNノードは長時間リクエストに対応不可

APIYIのapi-cf.apiyi.comは、CloudflareグローバルCDNをフロントに配置しています。世界規模の高速化と海外からの低レイテンシーを提供しますが、リクエストタイムアウトは約100秒であり、これを超えると524エラーが発生します。⚠️ これは画像エンドポイントだけに影響するわけではありません。 100秒を超える可能性のあるすべての呼び出しには適していません。これには以下が含まれます：

❌ 画像生成／編集
❌ 動画生成
❌ 長文テキスト出力（長文記事、大規模翻訳、巨大なコード生成）
❌ 推論モデルでのディープシンキングタスク

✅ 適している用途：100秒以内に完了する通常のチャットや短時間の生成。推奨事項：長時間のリクエストにはapi.apiyi.com（またはバックアップのb.apiyi.com）を使用してください。全ノードの比較についてはBase URLガイドを参照してください。

④ 429同時実行数制限への到達：サポートにお問い合わせください

頻繁な429 Too Many Requestsとともにタイムアウトが発生する場合、問題は通常タイムアウトの設定ではなく同時実行数クォータにあります。同時実行数制限はアカウント全体ではなく、モデルごとに適用されます。特定のモデル（特に新規リリースされたモデルや供給が制限されているモデル）は、クォータが低く設定されている場合があります。対処方法：

一時的なスパイクで制限に達しないよう、指数バックオフを実装する
429エラーが解消しない場合は、APIYIサポートにお問い合わせください — 該当モデルの実際のクォータを確認し、調整をサポートいたします

ルールについてはどれくらいの同時実行数を利用できますか？を参照してください。

コード例

Python
Node.js
cURL

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1",  # not the api-cf node for long requests
)

# Tier your timeouts by scenario (seconds) instead of one global value
TIMEOUTS = {
    "text":      120,   # regular text
    "reasoning": 600,   # reasoning models
    "image":     360,   # image generation baseline
    "image_4k":  600,   # 4K / multi-image reference
}

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Analyze the complexity of this code"}],
    timeout=TIMEOUTS["reasoning"],   # 600s for reasoning models
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.APIYI_API_KEY,
  baseURL: "https://api.apiyi.com/v1",
  timeout: 600 * 1000,   // milliseconds — 600s for reasoning models
  maxRetries: 0,         // avoid auto-retry on long requests: it double-bills
});

const resp = await client.chat.completions.create({
  model: "gemini-3.1-pro-preview",
  messages: [{ role: "user", content: "Write an 8000-word technical analysis" }],
});
console.log(resp.choices[0].message.content);

# --max-time caps the total request duration in seconds
curl https://api.apiyi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 360 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a serene mountain lake at sunrise",
    "size": "2048x2048"
  }'

長時間のリクエストで自動再試行に注意してください: 多くの SDK はデフォルトで 2 回再試行します。画像生成や推論タスクがタイムアウトして再試行されると、何も得られないまま 3 回分課金される可能性があります。max_retries を 0 に設定し、再試行はご自身のアプリケーションロジックで制御してください。

タイムアウトを延長してもまだタイムアウトが発生しますか？すべてのホップを確認してください

ステップ1：SDKのタイムアウトが実際に適用されているか確認する

一部のフレームワークは、HTTPクライアントを別のタイムアウトでラップしています。有効な設定を出力し、変更したパラメータが実際に使用されていることを確認してください。

ステップ2：経路上にあるすべてのホップを確認する

生成時間よりも短いタイムアウトが設定されているレイヤーが存在すると、クライアントよりも先に切断されてしまいます：

セルフホストのリバースプロキシ：Nginx proxy_read_timeout（デフォルトで60秒）
クラウドロードバランサー：アイドル接続タイムアウト
APIゲートウェイ / CDN：オリジンタイムアウト
サーバーレス関数：実行時間制限（多くの場合デフォルトで30〜60秒）
タスクキューワーカー：タスクごとのタイムアウト

すべてのホップの制限を緩和する必要があります — クライアント側だけを変更しても効果はありません。

ステップ3：CDNノード経由になっていないか確認する

Base URL が api-cf.apiyi.com になっていないか確認してください。実行時間の長いリクエストの場合は、api.apiyi.com または b.apiyi.com に切り替えてください。経験則：524 は、モデルの応答が遅いのではなく、ほぼ確実にCloudflareレイヤーでのタイムアウトを意味します。

ステップ4：タイムアウトと同時実行数の制限を区別する

ステータスコードを確認してください：524 や接続の切断はタイムアウトの問題ですが、429 はクォータの問題です。対処法はまったく異なります。

ステップ5：呼び出しログで実際のレイテンシを確認する

コンソールの呼び出しログでリクエストの実際の所要時間と課金を確認し、それに基づいて適切なタイムアウト値を導き出してください。

よくある質問

画像のタイムアウトを200秒に設定しており、普段はこれで十分です。なぜ時々タイムアウトが発生するのですか？

ほとんどの画像は数十秒で完了するため、200秒あれば十分に見えます。しかし、ピーク時にはプロバイダー側でリクエストがキューイングされ、1回の生成に数分かかることがあります。その際、クライアント側が待機状態を維持している限り、ゲートウェイはバックグラウンドで自動的に別のルートで再試行します。タイムアウトが短すぎると、ゲートウェイがルートを切り替える前にクライアント側で接続が切断され、リクエストは単に失敗してしまいます。そのため、画像生成では自動切り替えのための余裕を持たせるよう、タイムアウトを360秒、4Kや複数の参照画像を使用する場合は600秒（上記の表を参照）に設定してください。また、参照画像のサイズが大きいほど処理が遅くなります。リクエストボディが8〜10MBの編集リクエストでは、アップロードだけでも時間を要し、プロバイダー側の処理時間も長くなります。ユースケースで許容される場合は、参照画像の長辺を2048ピクセル以下、各ファイルサイズを2MB未満に圧縮してください。品質にほとんど影響を与えることなく、処理速度が顕著に向上します。詳細は画像の圧縮と解像度をご覧ください。

タイムアウトしたリクエストについて返金を受けることはできますか？

いいえ、できません。クライアントが接続を切断した後も、サーバーおよびアップストリーム側ではジョブが完了まで処理されるため、費用は実際に発生します。正しいアプローチは、短い値を設定して再試行に頼るのではなく、最初から安全な上限値にタイムアウトを設定することです。再試行を繰り返すと請求額が膨らむだけです。

切断後にIDで結果を取得できるように、非同期エンドポイントを提供してもらえませんか？

画像の各エンドポイントは現在同期パススルーモードで動作しており、お客様の業務データを保存しないため、「切断後にIDで取得」する機能は利用できません。推奨パターン：同期呼び出し＋余裕を持ったタイムアウト＋独自のタスク状態管理テーブル。これにより、実質的な軽量の非同期キューとして機能します。詳細は画像エンドポイントは同期ですか、それとも非同期ですか？をご覧ください。なお、動画モデルはネイティブで非同期であるため、この影響は受けません。

ストリーミングを使用すればタイムアウトを防げますか？

ある程度は防げますが、これに依存すべきではありません。ストリーミングは最初の token をより早く配信するため、応答が一切ない状態に陥るリスクを減らせます。しかし、推論モデルは思考フェーズ中に何も出力しない場合があるため、読み取りタイムアウトが依然として発生する可能性があり、全体の出力完了までにかかる時間は変わりません。正しいアプローチは、ストリーミングに加えて余裕を持ったタイムアウトを設定することです。

タイムアウトを非常に大きな値に設定するデメリットはありますか？

課金への影響はありません。待機時間ではなく、消費された tokens や呼び出し回数に対して課金されます。懸念される点は、クライアント側のリソース消費のみです。長時間の接続はワーカーや接続プールのスロットを占有します。高い同時実行数の環境では、画像生成や推論のリクエストを非同期IOまたは専用の長時間タスク用キュー経由で実行してください。

524と429の違いは何ですか？

524：Cloudflareレイヤーのタイムアウトです。api-cf.apiyi.com を使用しており、リクエストが約100秒を超えたことを意味します。ノードを切り替えてください。
429：同時実行数またはレート制限によるものであり、所要時間とは関係ありません。指数バックオフを追加し、問題が解決しない場合はサポートにお問い合わせください。

Image APIのベストプラクティス

モデルごとのタイムアウト表と出力形式のリファレンス

Base URL はどのように設定しますか？

4つのノードの違いと選び方

画像エンドポイントは同期ですか、それとも非同期ですか？

同期モードとクライアント側のタスク管理

どの程度の同時実行数を使えますか？

モデル種別ごとの同時実行数の制限とクォータ申請

お問い合わせ

WeCom サポート

QRコードをスキャンするか、クリックしてサポートに連絡タイムアウトのトラブルシューティングと同時実行数クォータの申請

メール

サポート: [email protected]営業: [email protected]

概要

サイト機能

tokensとログ

法人向けサービス

課金とセキュリティ

ネットワークと接続

アカウントとログイン

API タイムアウトを回避するには？

簡潔な回答

タイムアウトチートシート

4つの重要ポイントの詳細

コード例

タイムアウトを延長してもまだタイムアウトが発生しますか？すべてのホップを確認してください

よくある質問

関連ドキュメント

Image APIのベストプラクティス

Base URL はどのように設定しますか？

画像エンドポイントは同期ですか、それとも非同期ですか？

どの程度の同時実行数を使えますか？

お問い合わせ

WeCom サポート

メール

​簡潔な回答

​タイムアウトチートシート

​4つの重要ポイントの詳細

​コード例

​タイムアウトを延長してもまだタイムアウトが発生しますか？すべてのホップを確認してください

​よくある質問

​関連ドキュメント

Image APIのベストプラクティス

Base URL はどのように設定しますか？

画像エンドポイントは同期ですか、それとも非同期ですか？

どの程度の同時実行数を使えますか？

​お問い合わせ

WeCom サポート

メール

簡潔な回答

タイムアウトチートシート

4つの重要ポイントの詳細

コード例

タイムアウトを延長してもまだタイムアウトが発生しますか？すべてのホップを確認してください

よくある質問

関連ドキュメント

お問い合わせ