GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
Все руководства

· reAPI Team

Статус API fal: COMPLETED, но результата нет

Разберись в статусе API fal, когда COMPLETED не даёт результата. Проверь ответы с результатом, ошибки, поля вывода и вебхуки, прежде чем повторять запрос генерации.

Статус API fal: COMPLETED, но результата нет

COMPLETED — неудачное место, чтобы прекратить чтение. В API очереди fal это означает, что запрос завершён, включая запросы, которые завершились ошибкой или были отменены. Это не говорит о том, что было создано пригодное для использования изображение или видео.[1]

Следующий вызов нужно направить к эндпоинту результата исходного запроса. Этот ответ содержит HTTP-статус и тело ответа модели.[2] Если приложение уже окрасило индикатор прогресса в зелёный, но не находит файл, разберись с этим результатом, прежде чем отправлять новую генерацию. Возможно, ты пропустил один шаг получения, читаешь не тот JSON-объект или столкнулся с реальной ошибкой модели.

Статус показывает, когда получать результат

Статус очереди fal проходит через IN_QUEUE, IN_PROGRESS и COMPLETED. Как только он достигает COMPLETED, прочитай результат. Такие поля, как metrics.inference_time, и любая доступная информация об ошибках дают полезный контекст, но не заменяют ответ модели.[1]

Это разделение видно и в собственных примерах API fal: отправь запрос, получи его статус, затем получи результат и сверься с Output Schema модели. Методы fal.queue.status() и fal.queue.result() клиента JavaScript выполняют разные операции. В 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Учётные данные, заголовок и аккаунт, использованные для проверки
404ID запроса, 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 недостаточно: прочитай статус задачи и проверь то, что нужно твоему приложению. Смена провайдера не устраняет этап обработки файла.

Вебхуки добавляют ещё один объект, который нужно различать

Статусы вебхуков fal используют OK и ERROR вместо значений жизненного цикла очереди. Уведомление OK может содержать payload: null и payload_error, когда результат невозможно представить в JSON. Документация направляет обратно к результату очереди для восстановления.[11]

Если твой рабочий процесс управляется вебхуками, проверь уведомление целиком, прежде чем решать, что результата нет. Парсер для поля status очереди не следует без изменений использовать для статуса и полезной нагрузки вебхука. Сопоставь уведомление с существующим запросом, затем получи результат, если этого требуют его поля.

Для долгих заданий fal рекомендует статус очереди и вебхуки вместо бессрочного удержания открытого блокирующего вызова.[3] Сохраняй маршрут проверки в собственном рабочем процессе, даже если обратные вызовы — обычный путь. Пропущенное уведомление должно оставлять тебе ID для расследования, а не вынуждать запускать новую генерацию ради продолжения процесса.

Оперативно сохраняй завершённые результаты. Доступность результатов очереди, хранение полезной нагрузки в истории запросов и хранение медиафайлов — отдельные вопросы; размер результата и настройки хранения могут влиять на них по-разному.[2][11][12] Если файл понадобится позже, скопируй его в контролируемое тобой хранилище и запиши, удалась ли копия. Один сохранённый URL — ещё не архив.

Когда проверять наличие сбоя сервиса

Если исходный результат не удаётся получить, сопоставь время ошибки и затронутый сервис с официальной страницей статуса fal и историей инцидентов. Страница разделяет компоненты, поэтому смотри на часть, относящуюся к твоему запросу, а не считай любое уведомление объяснением каждой ошибки.[13] Эта статья не даёт оценки доступности в реальном времени.

Завершённый статус без отображаемого файла сам по себе не доказывает, что fal не работает. Отсутствие уведомления на странице статуса тоже не доказывает, что твой код неверен. Следующим полезным свидетельством остаётся исходный ответ с результатом: его HTTP-код, тело, эндпоинт и ID запроса. Получив их, ты сможешь решить, нужно ли исправить получение, скорректировать ввод, восстановить файл или передать нерешённую ошибку сервиса на дальнейшее рассмотрение.

Источники

  1. fal. Получение статуса запроса. Справочник API очереди. Дата обращения: 15 ноября 2026 г.
  2. fal. Получение результата запроса. Справочник API очереди. Дата обращения: 15 ноября 2026 г.
  3. fal. Очередь. Руководство по инференсу API моделей. Дата обращения: 15 ноября 2026 г.
  4. fal. Методы инференса: как вызывать модели fal. Дата обращения: 15 ноября 2026 г.
  5. fal. Получение ключа API. Дата обращения: 15 ноября 2026 г.
  6. fal. Ошибки модели. Включая запись no_media_generated. Дата обращения: 15 ноября 2026 г.
  7. fal. Ошибки запроса. Руководство по API моделей. Дата обращения: 15 ноября 2026 г.
  8. fal. FLUX.1 [dev] API. Разделы Files и Schema. Дата обращения: 15 ноября 2026 г.
  9. reAPI. Задачи. reapi.ai/docs/api/tasks. Дата обращения: 15 ноября 2026 г.
  10. reAPI. Ошибки. reapi.ai/docs/api/errors. Дата обращения: 15 ноября 2026 г.
  11. fal. Вебхуки. Руководство по инференсу API моделей. Дата обращения: 15 ноября 2026 г.
  12. fal. Хранение данных. Руководство по API моделей. Дата обращения: 15 ноября 2026 г.
  13. fal. Статус fal. Интерфейс официальной страницы статуса проверен 15 ноября 2026 г.; оценка доступности здесь не утверждается.
Все руководства