Skip to main content
このページは、自社の製品に画像生成を統合する開発チーム向けの技術共有 / アドバイザリー記事です。ここで共有するのはエンジニアリングの実践のみで、APIYI側で何か変更を行う必要はありません。既存の同期APIの上に、そのすべてを実装できます。

​
同期か、非同期か？まずは APIYI の API モデルを理解しましょう

APIYI の画像生成 API はすべて同期です。/v1/images/generations のようなエンドポイントは、リクエストを「送信すると完了まで処理する」形で動作します。クライアントが途中で切断されても、サーバーは生成を最後まで完了します。つまり、「まず task_id を受け取り、そのあと結果をポーリングする」という非同期タスク APIではありません。
ゲートウェイ層では、APIYI がすでに上流の非同期ポーリング（プロバイダーによってはネイティブに polling_url ループを使います）を同期的な OpenAI Images API にラップしています。利用者側では常に「1 回送信して、1 回結果を受け取る」だけです。自分でポーリングループを書く必要はありません。
多くのチームはすぐにこう考えます。「では、非同期タスク管理はどうすればいいの？」実際には、この 2 つは別物です。
  • 同期 — APIYI API の形です（HTTP リクエストレベル: 1 回のリクエスト、1 つの結果）。
  • 非同期キュー — 利用者側の設計手法です（ビジネスタスクレベル: すぐに応答し、バックグラウンドで実行する）。
この 2 つは矛盾しません。以下では、同期 API の上に非同期キューを自分で重ねる方法を説明します。

​
なぜ開発チームは今でも「タスクレベル」の管理を必要とするのか

画像 API をユーザーのリクエストスレッド内で同期的に呼び出すのは、デモなら問題ありません。ですが、実際にエンドユーザー向けの本番プロダクトを作る段階になると、「ビジネスタスク」と「単一の HTTP 呼び出し」を切り離す必要がほぼ確実に出てきます。理由は 4 つあります。

成功 ≠ 1 回の呼び出し

「成功したタスク」は、しばしば複数の同期呼び出しをつなぎ合わせて成立します。最初のタイムアウトや、たまに発生する 429/503 はリトライが必要です。タスクと呼び出しを分離すると、リトライ、バックオフ、タイムアウトはすべてエンドユーザーからは見えなくなり、ユーザーが目にするのは「この画像は最終的に成功した」という結果だけです。

透明転送、保存なし

APIYI は透明転送のみを行い、ユーザー入力や出力を保存しません（prompt、参照画像、生成結果は保持されません）。ユーザーに履歴、状態照会、結果の永続化を提供するには、自分で保存する必要があります。これはプロダクト側で避けられない工程です。

エンドユーザーにやさしい UX

ユーザーは送信時に task_id を受け取り、frontend は長時間の接続を張り続ける代わりにタスク状態をポーリングします。ページを再読み込みしても、短時間のネットワーク切断があってもタスクは失われません。バッチ生成もキューに積んで、1 件ずつ埋めていけます。

複数プロバイダ対応が可能に

独自のタスク抽象を持てば、Worker レイヤーは必要に応じて 複数のプロバイダ 間で切り替え / フェイルオーバー / 価格比較を行えます。少なくとも、「卵を一つのかごに盛らない」ことを可能にします。

​
リファレンスアーキテクチャ: 同期呼び出しを非同期キューで包む

核心となる考え方は一文です。API 層は「タスクを受け取り、キューに入れて、task_id を返す」だけで、実際の同期呼び出しはバックグラウンド Worker が行います。
1

すぐに返す

フロントエンドは生成リクエストを自分の API 層に送信します。API 層はタスクレコード（ステータス pending）を作成してキューに投入し、task_id をフロントエンドへ即座に返します。ユーザーは待たされることがなく、ミリ秒単位で応答が返ります。
2

キューに投入

キューは軽量なもので十分です。Redis List / Stream、RabbitMQ / Kafka、あるいはスケジュールで走査する status 列付きのデータベーステーブルでも構いません。どれを選ぶかは規模次第で、最初から重いミドルウェアを使う必要はありません。
3

Worker: 同期呼び出し + リトライ

バックグラウンド Worker がタスクを取り出し、ステータスを running に設定して、APIYI の画像 API を同期的に呼び出します。リトライ可能なエラーでは、指数バックオフでリトライします（下の「リトライと課金」を参照）。これらはすべてユーザーからは透過的です。
4

永続化

成功しても失敗しても、結果をデータベースに書き戻します。成功時は出力画像 URL、レイテンシ、課金メタデータを保存し、ステータスを succeeded に設定します。失敗時はエラーを保存し、ステータスを failed に設定します。ここはまさに APIYI が代わりにやってくれない部分であり、ご自身で実装する必要があります。
5

フロントエンドのポーリング

フロントエンドは定期的に task_id でタスクステータスを確認します（または WebSocket / SSE 経由でプッシュします）。タスクが完了したら結果を表示し、失敗したら分かりやすいメッセージを表示します。ユーザーのブラウザが長時間接続を保持する必要はありません。

​
タスクの状態マシンとデータモデル

各タスクのライフサイクルは、明確な状態マシンで表します。 タスクテーブルには、少なくとも次のフィールドを記録してください（型はスタックによって異なります）。
生成された結果は 自前のオブジェクトストレージ（OSS / S3 など）に再ホストし、その URL を永続化してください — サードパーティの一時リンクに長期的に依存しないでください。一時リンクは期限切れになることがあるため、自前のコピーを保持したほうがエンドユーザーにとって安定します。

​
リトライと課金: 何を再試行し、何を再試行しないか

「タスク単位の管理」で最も価値があるのは、リトライを正しく扱えることです。課金とリトライ戦略はエラーの種類ごとに異なります。
「ビジネスタスクのリトライ回数」と「課金されたかどうか」は別々に考慮してください。429/503 のリトライは課金されないため、遠慮なくバックオフできます。しかし、タイムアウトによる切断やコンテンツ安全性の拒否は、「失敗」していても課金されます。やみくもに再試行するとコストが増幅します。再度費用を発生させる前に、まずエラー種別を確認してください。
エラー判定と親切なメッセージングの完全な基準については、以下を参照してください。

Gemini 画像エラーハンドリング

失敗検出シグナル、コンテンツモデレーションポリシー、親切なメッセージ戦略。

生成失敗保証

あなたに起因しない失敗については、クレジットが件数ベースで返還されます。

​
上級編: 1つのキュー、複数のプロバイダー

タスク抽象化を使うと、Worker の呼び出しを「1つのエンドポイントにハードコードされている状態」から「providerによってルーティングされる状態」へ移せます。単一のsubmit(provider, payload)エントリに統一し、Worker にタスクのproviderフィールドに基づいて実際の上流先を判断させます。
  • フェイルオーバー: プロバイダー A が失敗し続ける場合に、ユーザーに気付かれない形で自動的に B に切り替えます。
  • 価格比較 / ルーティング: コストやシナリオに応じて、異なるタスクを異なるプロバイダーやモデルへ振り分けます。
  • カナリア: 新しいモデルに少量のトラフィックを送って検証し、その後で段階的に増やします。
多くの場合、実は自前のマルチプロバイダー層は不要です。APIYI 自体が gpt-image-2、Nano Banana、FLUX、Seedream などを集約しているため、1つの APIYI キーで 1つの API スタイルのままほとんどの要件をカバーできます。自前のプロバイダー抽象化は「念のため」の選択肢であり、プロバイダー横断のフェイルオーバーや価格比較が本当に必要なときだけ追加してください。

​
よくある質問

画像生成は本質的に「1回送信して、1枚の画像を受け取る」という強い同期的な意味合いを持っており、ほとんどの利用者にとっては同期 API として包むのが最も簡単です（ポーリングの維持も、タスク期限切れへの対応も不要です）。非同期キュー、ステートマシン、永続化が必要かどうかは、あなたのプロダクトの形（エンドユーザー向けかどうか、履歴が必要かどうか）によるため、最大限の柔軟性のために、その部分は必要に応じてご自身で実装してください。
実行は継続されます。同期エンドポイントは一度リクエストを受け取ると完了まで実行されるため、クライアントの切断ではサーバー側の生成は中断されず、その生成は通常どおり課金されます。そのため、解像度に応じて十分なタイムアウトを設定してください（約60〜600秒）——短くしすぎて「画像を受け取れないのに支払う」ことがないようにしてください。
いいえ。APIYI は透過的な転送のみを行い、ユーザーの入力や出力を保存しません。ユーザーに履歴、ステータス照会、結果の永続化を提供するには、あなた側で永続化する必要があります——だからこそ、このガイドでは「タスクレベルの管理」を推奨しています。
通常は不要です。APIYI はすでに複数のモデルファミリーを 1 つの API スタイルにまとめており、単一のキーで十分なことがほとんどです。クロスプロバイダーのフェイルオーバー、価格比較、コンプライアンスルーティングといった明確な要件がある場合にのみ、Worker 層にプロバイダー抽象化を追加することを検討してください。これは任意であり、必須ではありません。

​
関連ドキュメント

Image API の基礎とベストプラクティス

モデルごとのタイムアウト表、base64 の取り扱い、URL 出力のリファレンスです。

非同期 API がない理由

FAQ: 非同期の画像 API はありますか？ task ID で結果を問い合わせできますか？

FLUX の概要

上流の非同期ポーリングを同期的な OpenAI Images API にラップした例です。

Nano Banana 開発ガイド

同期マルチスレッド呼び出し、タイムアウト設定、課金の基本をまとめて確認できます。

Gemini 画像エラー処理

失敗検知シグナルと親しみやすいメッセージ戦略です。

生成失敗保証

ご自身が原因ではない失敗に対するクレジット返還ルールです。