· reAPI Team
fal API の状態:COMPLETED なのに結果がない
COMPLETED なのに結果がない場合の fal API の状態を理解しましょう。生成リクエストを再試行する前に、結果レスポンス、エラー、出力フィールド、Webhook を確認します。

COMPLETED で確認を止めてしまうと、問題を見落とします。fal のキュー API では、これは失敗やキャンセルも含めてリクエストが終了したことを意味します。使用可能な画像や動画が生成されたことを示すものではありません。[1]
次に呼び出すのは、元のリクエストの結果エンドポイントです。そのレスポンスには、モデルの HTTP ステータスと本文が含まれます。[2] アプリの進行状況表示が緑になってもファイルが見つからない場合は、別の生成を送信する前に、その結果をたどってください。取得手順が一つ抜けている、別の JSON オブジェクトを読んでいる、あるいは実際のモデルエラーが発生している可能性があります。
状態は結果を取得するタイミングを示します
fal のキュー状態は IN_QUEUE、IN_PROGRESS、COMPLETED の順に進みます。COMPLETED に達したら、結果を読み取ります。metrics.inference_time などのフィールドや、利用可能なエラー情報は参考になりますが、モデルのレスポンスの代わりにはなりません。[1]
この分離は fal 自身の API サンプルにも見られます。リクエストを送信し、状態を取得してから、結果を取得し、モデルの Output Schema を参照します。JavaScript クライアントの fal.queue.status() と fal.queue.result() は異なる処理を行います。Python では、完了状態の後に handler.get() を呼び出します。[3][4]
アプリケーションが画像コンポーネントに渡している変数を確認してください。キュー状態が入っているなら、コンポーネントが必要とするオブジェクトにはまだ到達していません。先に結果を取得します。JavaScript SDK の結果ラッパーが入っているなら、モデルの出力スキーマを適用する前に、その data プロパティを読み取ってください。[3] 試行錯誤で images を image に変えるより、実際にどのレスポンスを持っているか確認するほうが有用です。
ここでは呼び出し方法が重要です。subscribe() は送信とキュー内での待機を代行しますが、submit() は制御を返し、アプリケーションでライフサイクルを管理できるようにします。直接の run() はキューを使いません。[4] そのため、ある方法向けのサンプルには、あなたのコードでまだ必要な待機やラッパーの展開手順、あるいは既に実行済みの手順が含まれている可能性があります。
元の送信で返された URL を使います
送信が成功したら、request_id、status_url、response_url を保存してください。fal のキューガイドは返された URL の使用を推奨しています。クエリ URL を自分で組み立てる場合、同ガイドでは owner/app パスと、処理の送信に使う完全なモデルエンドポイントパスを区別しています。[3] リクエスト状態のルートにすべてのモデル接尾辞を追加すると、照会先を誤る可能性があります。
再起動する可能性のあるワーカーでは、待機前にそれらの値をプロセス外に保存します。そうすれば、ローカルジョブは同じリクエストを読み取って処理を続けられます。これはアプリケーション設計上の推奨です。結果が存在するか確認するだけのために、再試行ボタンで元の送信を再構築する必要はないはずです。
次の JavaScript は、ご自身のサーバーに保存したリクエストを読み取ります。URL は任意のブラウザー入力ではなく、そのサーバーの信頼できる fal 送信レスポンスに由来する必要があります。このリクエストにはお客様の API 認証情報が付加されるためです。
async function inspectFalRequest(saved, key) {
async function read(url) {
const response = await fetch(url, {
headers: { Authorization: `Key ${key}` },
redirect: "error",
});
const raw = await response.text();
let body;
try {
body = JSON.parse(raw);
} catch {
body = raw;
}
return { http: response.status, ok: response.ok, body };
}
const state = await read(saved.status_url);
const lifecycle = state.body?.status;
if (!state.ok || !["IN_QUEUE", "IN_PROGRESS", "COMPLETED"].includes(lifecycle)) {
return { stage: "status-read-error", ...state };
}
if (lifecycle !== "COMPLETED") {
return { stage: "pending", ...state };
}
const result = await read(saved.response_url);
return { stage: "result", ...result };
}このヘルパーは、JSON ではないレスポンスを意図的にテキストとして保持します。そうしなければ、JSON の解析失敗によって、有用なエラーが別の例外に置き換わる可能性があります。接続失敗は引き続き呼び出し元に例外として送出されます。次の復旧手順で同じジョブを調べられるよう、保存済みリクエストを保持してください。この関数は生成の POST を行いません。
ok フラグは読み取りの HTTP 結果であり、製品で使用可能な素材があることを示すものではありません。本文の確認は依然として必要です。同様に、status-read-error はこの照会でキュー状態を確認できなかったことを意味します。リモートの生成が失敗したという意味ではありません。
Python では、handler.get() の呼び出し自体に加えて、その周囲の例外処理も確認してください。あらゆる例外に None を返す広範なハンドラーでは、アプリの次の部分に説明のない空の値が渡されます。診断のために例外情報を保持し、アプリケーションに独立したエラー経路を設けてください。まだ待機中のリクエスト、拒否された入力、正常に生成されたものの未ダウンロードのファイルを、同じ空の値で表さないでください。
JavaScript のデバッグ中は、機密情報を除去したレスポンスのフィールド名の記録が、誤ったオブジェクトパスの発見に役立つことがあります。認証情報や非公開の入力内容を共有ログに残さないでください。パスが分かったら、画像や動画のコンポーネントに結果を渡す前に必須フィールドを検証します。
認証が問題なら、タスクを作成したアカウントを確認します。fal のキーはダッシュボードの Keys 領域で作成され、選択中のアカウントに属します。認証情報はサーバー側に保持し、一般的には FAL_KEY に入れます。生のリクエストでは Authorization: Key ... を使います。[5] 別のアカウントでキーを作成しても、既存のリクエストはそのアカウントに移りません。デバッグを簡単にするために、有効なキーをブラウザーのコードに入れないでください。
失敗が発生した場所でエラーを読みます
結果レスポンスから、完了したリクエストにメディアがない理由が分かることがあります。fal は次の結果ステータスを文書化しています。[2]
| 結果レスポンス | 確認する内容 |
|---|---|
400、リクエストは処理中 | 保存した状態 URL に戻り、そのリクエストを引き続き観察します |
401 | 照会に使った認証情報、ヘッダー、アカウント |
404 | リクエスト ID、クエリ URL、アカウント、適用される保持ルール |
422 | 返された検証エラーまたはモデルエラー |
499 | 記録されたキャンセル |
500 または別のサーバーエラー | 実際のレスポンス本文とリクエスト ID |
最後の行を接続タイムアウトと一括りにしないでください。結果エンドポイントからモデルエラーを受け取った場合は、調べられるレスポンスがあります。エンドポイントに到達できなかった場合、そのレスポンスはありません。復旧の判断は異なります。
例えば、no_media_generated は文書化された 422 モデルエラーで、期待するメディアを生成せずに処理が終了したことを示します。fal は再試行不可としています。[6] 返されたエラーがそう述べている場合に使える具体的な診断です。画像コンポーネントが空というだけで、自分でその診断を下すことはできません。
エラーの構造をそのまま保持してください。リクエストエラーには文字列の detail と error_type が含まれる場合があり、モデルの検証エラーには型付きの項目からなる detail 配列が含まれる場合があります。また fal は、一部のエンドポイントが新しいモデルエラー形式をまだ採用していないと説明しています。[6][7] すべてのエラーが一つの構造を持つと想定するパーサーは、最も必要なメッセージを隠してしまう可能性があります。
結果にファイル入力エラーが示されたら、元のファイルも調べてください。ログイン済みのブラウザーで使える URL でも、サービスが公開アクセスで取得できるとは限りません。fal のファイルガイドはアクセス可能な入力 URL を要求し、ホストがリクエストを遮断したりレート制限したりする可能性を指摘しています。[8] 出力パーサーを変更する前に、その条件を確認してください。入力取得の失敗と出力フィールドの誤りは別の段階で発生します。
したがって、アプリの「API 呼び出し失敗」は調査の出発点であり、説明ではありません。どの呼び出しが失敗したかを記録し、その状態と本文を保持してください。失敗にクレジットがかかるべきだったか判断する場合は、実際のリクエスト結果を特定してから失敗リクエストの課金ガイドを参照してください。
成功した JSON レスポンスでもメディアの確認は必要です
実際に送信したエンドポイントの Output Schema を開いてください。一部の画像モデルは images 配列を返し、ほかのモデルは異なる構造を使います。sync_mode を公開しているものもあり、メディアを data URI として返し、リクエスト履歴から出力を省くことができます。[8] これらはモデル固有の詳細です。すべての結果にダウンロード可能な video.url が一つ含まれると想定する汎用ハンドラーでは対応できません。
代わりに、モデルレスポンスに期待どおりの出力 URL があるものの、ストレージへのアップロードに失敗したと仮定します。これは仮の復旧例です。URL と元のリクエスト ID を保持し、ファイルが利用可能な間に転送手順を再試行して、保存したバイト列を読み取れることを検証します。生成を再実行すると、元のファイルに何が起きたかを説明できない新たな操作が発生します。
API 移行でも、ここで明示的なフィールド対応付けが必要です。通常の reAPI メディアタスクは、一つのタスクレスポンスで業務上の状態とメディア配列を返し、output.image_urls または output.video_urls を使います。タスクリファレンスとエラーリファレンスでは、メディア結果がない場合と生成ファイルの保存に失敗した場合を区別しています。[9][10] そこでも HTTP 200 だけでは不十分です。タスクの状態を読み、アプリケーションに必要な内容を検証してください。プロバイダーを変えても、ファイル処理の手順はなくなりません。
Webhook では、さらに別のオブジェクトを区別する必要があります
fal の Webhook 状態は、キューのライフサイクル値ではなく OK と ERROR を使います。結果を JSON で表せない場合、OK 通知に payload: null と payload_error が含まれることがあります。文書では、復旧のためにキュー結果に戻るよう案内しています。[11]
Webhook 主導のワークフローでは、結果がないと判断する前に通知全体を確認します。キューの status フィールド用のパーサーを、Webhook の状態とペイロードに変更せず流用するべきではありません。通知を既存のリクエストに照合し、そのフィールドが要求している場合は結果を取得してください。
長時間のジョブについて、fal はブロッキング呼び出しを無期限に開いたままにするのではなく、キュー状態と Webhook を推奨しています。[3] コールバックが通常の経路であっても、自分のワークフロー内に照会経路を保持してください。通知を逃しても、調査できる ID が残り、ワークフローを再開するために新たな生成を強いられないようにします。
完了した結果は速やかに保存してください。キュー結果の可用性、リクエスト履歴のペイロード保存、メディアファイルの保持は別々の問題です。結果のサイズやストレージ設定がそれぞれに異なる影響を与える可能性があります。[2][11][12] 後でファイルが必要なら、自分で管理するストレージにコピーし、コピーが成功したか記録します。URL を保存しただけではアーカイブにはなりません。
障害を確認するタイミング
元の結果を取得できない場合は、失敗時刻と影響を受けたサービスを、fal の公式ステータスページおよびインシデント履歴と照合します。ページはコンポーネントを分けているため、どんな通知もすべてのエラーの説明とみなすのではなく、リクエストに関係する部分を確認してください。[13] この記事はリアルタイムの稼働状況を評価するものではありません。
完了状態なのにファイルが表示されないというだけでは、fal が停止しているとは断定できません。状態通知がないからといって、コードが誤っていると証明されるわけでもありません。次に役立つ証拠は、依然として元の結果レスポンスの HTTP コード、本文、エンドポイント、リクエスト ID です。それがあれば、取得の修正、入力の訂正、ファイルの復旧、未解決のサービスエラーのエスカレーションのどれを行うか判断できます。
参考文献
- fal. リクエスト状態の取得。 キュー API リファレンス。 2026 年 11 月 15 日参照。
- fal. リクエスト結果の取得。 キュー API リファレンス。 2026 年 11 月 15 日参照。
- fal. キュー。 モデル API 推論ガイド。 2026 年 11 月 15 日参照。
- fal. 推論方法:fal モデルの呼び出し方。 2026 年 11 月 15 日参照。
- fal. API キーの取得。 2026 年 11 月 15 日参照。
- fal. モデルエラー。
no_media_generated項目を含みます。 2026 年 11 月 15 日参照。 - fal. リクエストエラー。 モデル API ガイド。 2026 年 11 月 15 日参照。
- fal. FLUX.1 [dev] API. Files および Schema の節。 2026 年 11 月 15 日参照。
- reAPI. タスク。 reapi.ai/docs/api/tasks. 2026 年 11 月 15 日参照。
- reAPI. エラー。 reapi.ai/docs/api/errors. 2026 年 11 月 15 日参照。
- fal. Webhook。 モデル API 推論ガイド。 2026 年 11 月 15 日参照。
- fal. データ保持。 モデル API ガイド。 2026 年 11 月 15 日参照。
- fal. fal の状態。 公式ステータスページの画面を 2026 年 11 月 15 日に確認しました。ここでは稼働状況の評価は行っていません。