· reAPI Team
fal API 状态:COMPLETED 却没有结果
了解 fal API 显示 COMPLETED 却没有结果时的状态含义。在重试生成请求前,检查结果响应、错误、输出字段和 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 日查看官方状态页界面;此处不作可用性评估。