Перейти к основному содержанию
Эта страница — технический материал / рекомендации для команд разработки, интегрирующих генерацию изображений в свои продукты. Мы делимся только инженерными практиками — здесь не требуется никаких изменений со стороны APIYI. Вы можете реализовать все это поверх существующих синхронных API.

​
Синхронный или async? Сначала разберитесь с моделью API APIYI

APIYI image generation API — все синхронные: эндпоинты вроде /v1/images/generations выполняют запрос «до завершения» после отправки. Даже если клиент отключится посреди выполнения, сервер все равно завершит генерацию — то есть это не async API задач, где вы «сначала получаете task_id, а затем опрашиваете результат».
На уровне шлюза APIYI уже оборачивает upstream async polling (некоторые провайдеры нативно используют цикл polling_url) в синхронный OpenAI API для изображений. Для вас это всегда «отправить один раз, получить результат один раз» — не нужно писать цикл опроса самостоятельно.
Многие команды сразу спрашивают: «Тогда как мне управлять async-задачами?» На самом деле это две разные вещи:
  • Синхронный — формат API APIYI (на уровне HTTP-запроса: один запрос, один результат).
  • Async-очередь — инженерная практика на вашей стороне (на уровне бизнес-задачи: вернуть ответ сразу, а выполнение продолжить в фоне).
Эти два подхода не конфликтуют. Ниже показано, как самостоятельно обернуть async-очередь вокруг синхронного API.

​
Почему командам разработки по-прежнему нужно управление на уровне задач

Синхронный вызов image API внутри потока запроса пользователя годится для демо. Но как только вы строите реальный продукт для конечных пользователей, вам почти наверняка нужно отделить «бизнес-задачу» от «единственного HTTP-вызова». Четыре причины:

Успех ≠ один вызов

«Успешная задача» часто складывается из нескольких синхронных вызовов: первоначальный timeout или случайный 429/503 требуют повторной попытки. Когда задача и вызов разделены, повторные попытки, backoff и таймауты полностью прозрачны для конечного пользователя — он видит только «это изображение в итоге успешно сгенерировалось».

Прозрачная пересылка, без хранения

APIYI выполняет только прозрачную пересылку и не хранит пользовательские входные данные или выходные данные (prompt, референсные изображения и сгенерированные результаты не сохраняются). Чтобы дать пользователям историю, просмотр статуса и сохранение результатов, вы должны хранить их сами — неизбежный шаг на стороне продукта.

Более удобный UX для конечных пользователей

При отправке пользователь получает task_id, а frontend опрашивает статус задачи вместо того, чтобы держать долгое соединение. Обновление страницы или кратковременный обрыв сети не приведут к потере задачи; пакетная генерация может вставать в очередь и заполняться по одной.

Использование нескольких провайдеров становится возможным

Когда у вас появляется собственная абстракция задач, слой Worker может переключаться / выполнять failover / сравнивать цены между несколькими провайдерами по запросу — как минимум, это делает возможным принцип «не класть все яйца в одну корзину».

​
Справочная архитектура: оберните синхронный вызов в асинхронную очередь

Основная идея в одном предложении: уровень API только «получает задачу, помещает ее в очередь и возвращает task_id»; сам синхронный вызов выполняется во фоновом Worker.
1

Возврат немедленно

Фронтенд отправляет запрос на генерацию в ваш собственный уровень API; уровень API создает запись задачи (статус pending), помещает ее в очередь и сразу возвращает task_id фронтенду. Пользователь никогда не ждет — ответ приходит за миллисекунды.
2

Помещение в очередь

Очередь может быть легковесной: Redis List / Stream, RabbitMQ / Kafka или даже таблица базы данных со столбцом status, которую сканируют по расписанию. Выбор зависит от вашего масштаба — на старте не нужно сразу тянуть тяжелую middleware.
3

Worker: синхронный вызов + повтор

Фоновый Worker забирает задачу, переводит статус в running и синхронно вызывает APIYI image API. При ошибках, которые можно повторить, он выполняет повторы с экспоненциальной задержкой (см. «Повтор и тарификация» ниже), и все это прозрачно для пользователя.
4

Сохранение

Независимо от того, успешна ли операция или нет, запишите результат обратно в базу данных: при успехе сохраните URL выходного изображения, задержку и метаданные тарификации, установите статус succeeded; при ошибке сохраните ошибку и установите статус failed. Именно эту часть APIYI не делает за вас, и вы должны реализовать ее сами.
5

Периодический опрос фронтенда

Фронтенд периодически проверяет статус задачи с помощью task_id (или вы отправляете данные через WebSocket / SSE). Когда задача завершается, покажите результат; при ошибке — дружелюбное сообщение. Браузеру пользователя никогда не нужно держать длительное соединение.

​
Машина состояний задачи и модель данных

Используйте понятную машину состояний, чтобы описать жизненный цикл каждой задачи: Таблица задач должна содержать как минимум следующие поля (типы зависят от вашего стека):
Перенесите сгенерированный результат в свое объектное хранилище (OSS / S3 и т. д.) и сохраните этот URL — не полагайтесь надолго на временную ссылку стороннего сервиса. Временные ссылки могут истечь; хранить собственную копию стабильнее для конечных пользователей.

​
Повторы и тарификация: что повторять, а что нет

Самая большая ценность «управления на уровне задачи» — правильно настроить повторы. Тарификация и стратегия повторов зависят от типа ошибки:
Учитывайте отдельно “число повторных попыток бизнес-задачи” и “была ли она тарифицирована”. 429/503 повторные попытки не тарифицируются, поэтому смело увеличивайте задержку; но отключения из-за тайм-аута и отказы проверки безопасности контента тарифицируются даже когда они «сбоят» — слепые повторы увеличивают затраты. Проверьте тип ошибки, прежде чем снова тратить средства.
Полные критерии определения ошибки и дружелюбных сообщений см.:

Обработка ошибок изображений Gemini

Сигналы обнаружения сбоев, политика модерации контента и стратегия дружелюбных сообщений.

Гарантия при сбое генерации

За сбои, вызванные не вами, кредиты возмещаются по количеству.

​
Продвинутый уровень: одна очередь, несколько провайдеров

С помощью абстракции задачи вызов Worker может перейти от «жесткой привязки к одному endpoint» к «маршрутизации по provider». Сведите все к одной записи submit(provider, payload) и позвольте Worker определять фактический upstream на основе поля provider у задачи:
  • Failover: когда провайдер A продолжает сбоить, автоматически переключайтесь на B, незаметно для пользователя.
  • Сравнение стоимости / маршрутизация: направляйте разные задачи к разным провайдерам или моделям в зависимости от стоимости или сценария.
  • Canary: отправляйте небольшую долю трафика на новую модель для проверки, а затем постепенно увеличивайте объем.
В большинстве случаев вам на самом деле не нужен собственный многопровайдерный слой: сам APIYI агрегирует gpt-image-2, Nano Banana, FLUX, Seedream и другие, так что один ключ APIYI покрывает большинство потребностей в рамках одного стиля API. Собственная абстракция провайдеров — вариант «на всякий случай»; добавляйте ее только тогда, когда вам действительно нужно кросс-провайдерное аварийное переключение или сравнение стоимости.

​
Вопросы и ответы

Генерация изображений по своей природе — это «отправить один раз, получить одно изображение»: это сильная синхронная семантика, и обернуть ее в синхронный API проще всего для подавляющего большинства вызывающих сторон (не нужно поддерживать опрос, не нужно обрабатывать истечение срока жизни задачи). Нужны ли вам асинхронная очередь, конечный автомат и персистентность, зависит от формата вашего продукта (ориентирован ли он на конечного пользователя, нужна ли вам история), поэтому эту часть вы при необходимости реализуете сами для максимальной гибкости.
Она продолжает выполняться. Как только синхронный endpoint получает запрос, он выполняется до завершения; отключение клиента не прерывает генерацию на стороне сервера, и эта генерация тарифицируется как обычно. Поэтому задайте достаточный timeout в зависимости от разрешения (~60–600s) — не ставьте его слишком коротким и не оказывайтесь в ситуации, когда вы «платите, но не получаете изображение».
Нет. APIYI выполняет только прозрачную пересылку и не хранит входные или выходные данные пользователя. Чтобы предоставить пользователям историю, просмотр статуса и сохранение результатов, вам нужно хранить это на своей стороне — именно поэтому в этом руководстве рекомендуется «управление на уровне задач».
Обычно нет. APIYI уже агрегирует несколько семейств моделей в одном стиле API, и одного ключа, как правило, достаточно. Только если у вас есть явные потребности в аварийном переключении между провайдерами, сравнении цен или маршрутизации по требованиям соответствия, стоит добавить абстракцию провайдера в слой Worker — это опционально, а не обязательно.

​
Связанные документы

Основы и лучшие практики Image API

Таблица тайм-аута для каждой модели, обработка base64 и справка по выходным URL.

Почему нет Async API

FAQ: Есть ли Async image API? Можно ли запрашивать результаты по task ID?

Обзор FLUX

Пример асинхронного опроса upstream, обёрнутого в синхронный OpenAI Images API.

Руководство для разработчиков Nano Banana

Синхронные многопоточные вызовы, настройки тайм-аута и основы тарификации в одном месте.

Обработка ошибок генерации изображений Gemini

Сигналы обнаружения сбоев и стратегия дружелюбных сообщений.

Гарантия при сбое генерации

Правила возврата кредитов за сбои, не вызванные вами.