> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Есть ли асинхронный API для генерации изображений? Можно ли запрашивать результаты по ID задачи?

> Генерация изображений в APIYI поддерживает только синхронный режим — асинхронного запроса по ID задачи нет. В этой статье объясняется, почему так, и предлагается рекомендуемый подход.

## Краткий ответ

APIYI на данный момент **НЕ предоставляет интерфейс асинхронного запроса по task-ID для генерации изображений**. Все модели image generation работают **синхронно**: запрос открывает длинное соединение → ожидает генерацию → возвращает image напрямую.

Мы работаем как **upstream pass-through** и **не храним никакие бизнес-данные пользователя**, поэтому не можем предложить «повторное подключение по ID для получения ранее сгенерированного результата». Мы рекомендуем установить разумный timeout на стороне клиента, поддерживать соединение активным и вести записи запросов/ответов в вашем собственном backend.

<Info>
  **Если говорить простыми словами**: синхронные вызовы + разумный timeout + записи задач на стороне клиента = по сути легковесная асинхронная очередь, которую вы контролируете. Восприятие для конечного пользователя почти такое же.
</Info>

## Почему нет асинхронного запроса по Task-ID?

<CardGroup cols={3}>
  <Card title="Сквозная передача upstream" icon="forward">
    Наши эндпоинты генерации изображений в точности повторяют синхронное поведение официального upstream API, без дополнительного слоя очереди, который мог бы внести несогласованность или задержку
  </Card>

  <Card title="Конфиденциальность и безопасность в первую очередь" icon="shield">
    Для защиты конфиденциальности пользователей и безопасности данных мы **не записываем никакое бизнес-содержимое** (prompt, сгенерированные изображения), поэтому получение прошлых результатов по ID невозможно по замыслу
  </Card>

  <Card title="Синхронный режим покрывает большинство случаев" icon="check">
    При правильно настроенном timeout и подключении keep-alive подавляющее большинство запросов на генерацию изображений успешно завершается за один вызов
  </Card>
</CardGroup>

## Рекомендуемый подход

<Steps>
  <Step title="Используйте долгоживущие соединения + разумный timeout на клиенте">
    Установите timeout вашего HTTP client на безопасную верхнюю границу времени генерации модели (обычно 60–300 секунд в зависимости от модели) и включите keep-alive, чтобы промежуточные сетевые уровни не разрывали соединение раньше времени.

    Время генерации существенно отличается между моделями — обратитесь в support за **таблицей рекомендованных timeout по моделям**.
  </Step>

  <Step title="Ведите учет задач и ответов в своем backend">
    Поскольку мы не храним бизнес-данные, создавайте бизнес-ID задачи для каждого запроса и сохраняйте prompt, параметры и финальный результат (или ошибку) в вашей базе данных. Даже если frontend отключится, в вашем backend все равно останется полный журнал.
  </Step>

  <Step title="Реализуйте собственную async-обертку">
    Если вашему продукту обязательно нужен async-режим (например, frontend не может ждать долго выполняющийся вызов), добавьте тонкий async-слой в backend:

    * Frontend отправляет POST на task → backend ставит в очередь → возвращает бизнес-ID задачи
    * backend worker синхронно вызывает APIYI → записывает результат обратно в базу данных
    * Frontend опрашивает или подписывается через WebSocket, используя свой task ID

    По сути это эквивалентно нативному async API платформы, и все ваши данные остаются под вашим контролем.
  </Step>
</Steps>

## Клиентская асинхронная обертка (Справка)

```python theme={null}
# Pseudocode: implement an async shell in your own backend
def submit_image_task(prompt):
    task_id = uuid4()
    db.save(task_id, status="pending", prompt=prompt)
    queue.push({"task_id": task_id, "prompt": prompt})
    return task_id

def worker(job):
    try:
        # Synchronous call to APIYI, timeout sized for the model
        result = apiyi_client.images.generate(
            prompt=job["prompt"],
            timeout=180,
        )
        db.update(job["task_id"], status="done", url=result.url)
    except TimeoutError:
        db.update(job["task_id"], status="failed", error="timeout")

def query_image_task(task_id):
    return db.get(task_id)  # frontend polls your own backend by task_id
```

<Tip>
  **Ключевая идея**: идентификатор бизнес-задачи генерируется **вашим кодом** и сохраняется в **вашей базе данных**. APIYI отвечает только за шаг «синхронной генерации».
</Tip>

## Часто задаваемые вопросы

<AccordionGroup>
  <Accordion title="Мои синхронные вызовы постоянно завершаются по таймауту — что мне делать?">
    Большинство таймаутов связано либо с **слишком коротким таймаутом клиента**, либо с **промежуточным сетевым уровнем (reverse proxy, шлюз и т. д.), который преждевременно разрывает длительное соединение**.

    Порядок устранения неполадок:

    1. Проверьте, что таймаут чтения вашего HTTP-клиента увеличен до 60–300 секунд
    2. Проверьте, что у промежуточных уровней (nginx, API-шлюз, CDN) тоже увеличены таймауты
    3. Включите keep-alive, чтобы предотвратить принудительное разъединение
    4. Обратитесь в поддержку за рекомендуемым таймаутом для вашей конкретной модели
  </Accordion>

  <Accordion title="Вызов завершился по таймауту, но изображение, возможно, все-таки было сгенерировано — можно ли его восстановить?">
    К сожалению, нет. Мы работаем как upstream pass-through и не сохраняем результаты генерации. Если синхронный вызов прерывается из-за таймаута, **результат теряется**, и клиент должен повторить попытку.

    Решение — заранее установить достаточно большой таймаут, чтобы не обрывать запрос, который вот-вот должен был успешно завершиться.
  </Accordion>

  <Accordion title="Будут ли в будущем добавлены async-эндпоинты с task-ID?">
    Мы понимаем, что некоторые upstream-платформы работают медленно и что в таких случаях async удобнее. Мы **можем добавить async-возможности в будущем**, но сроков пока нет — никаких обещаний. До тех пор, пожалуйста, следуйте подходу «async-обертки на стороне клиента», описанному выше.
  </Accordion>

  <Accordion title="Эндпоинты генерации видео (Sora / VEO и т. д.) асинхронны?">
    **Да — генерация видео по своей природе асинхронна** (по задумке upstream). Она возвращает task\_id, а клиент опрашивает статус задачи, чтобы получить финальное видео. Это отличается от синхронных эндпоинтов генерации изображений — пожалуйста, следуйте документации для конкретной модели.
  </Accordion>

  <Accordion title="Какой рекомендованный таймаут для разных моделей генерации изображений?">
    Время генерации сильно различается между моделями (некоторым требуется несколько секунд, другим — 30+ секунд или даже 3–5 минут). См. **справочную таблицу по таймаутам для каждой модели** в [Основы и лучшие практики Image API](/ru/api-capabilities/image-api-best-practices) или обратитесь в поддержку для особых случаев.
  </Accordion>
</AccordionGroup>

## Связанная документация

<CardGroup cols={2}>
  <Card title="Основы и лучшие практики Image API" icon="book-check" href="/ru/api-capabilities/image-api-best-practices">
    Таблица таймаутов по моделям, обработка base64 и справка по выходным данным URL
  </Card>

  <Card title="Создайте собственную асинхронную очередь" icon="list-checks" href="/ru/api-capabilities/image-async-queue">
    Инженерное руководство по оборачиванию синхронного API в очередь задач
  </Card>

  <Card title="Руководство по выбору модели" icon="cpu" href="/ru/faq/model-selection-guide">
    Возможности и варианты использования каждой модели генерации изображений
  </Card>

  <Card title="Параллельные запросы API и лимит запросов" icon="gauge" href="/ru/faq/api-concurrency">
    Ограничения на параллельные запросы, лимит запросов и лучшие практики
  </Card>

  <Card title="Журналы вызовов и данные" icon="file-text" href="/ru/faq/user-logs-control">
    Наша политика хранения данных и управление журналами
  </Card>

  <Card title="Свяжитесь со службой поддержки" icon="message-circle" href="https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec">
    Получите таблицу таймаутов по моделям или дальнейшую консультацию
  </Card>
</CardGroup>