Обновление содержания: 2026-09-18

Асинхронное создание изображений

Обычно генерация изображения моделью занимает 20~120 секунд. Синхронный интерфейс требует поддерживать HTTP-соединение до получения результата, что чревато таймаутами прокси/шлюза, возвращаемый base64 также велик. Асинхронная схема разбивает процесс на два вызова:

Отправка: запрос немедленно возвращает 202 и ID задачи (меньше чем за 1 сек).
Опрос: по ID задачи запрашивается GET /v1/tasks/{id}, после завершения в result находится https URL изображения (навечно архивируется в media.crazyrouter.com), base64 не возвращается.

提交（三种触发方式，见下文）
  POST /v1beta/models/{model}:asyncGenerateContent      # Gemini 系，路径别名
  POST /v1/images/generations  + Prefer: respond-async   # OpenAI 系
  POST /v1/images/edits        + Prefer: respond-async   # OpenAI 系（带参考图）

查询
  GET  /v1/tasks/{task_id}

Имя модели, тело запроса и тарифы полностью совпадают с синхронным режимом. Асинхронность меняет только “когда получаете результат”, один и тот же API Key может часть запросов выполнять синхронно, часть асинхронно. Неудачные задачи не тарифицируются.

Поддерживаемые модели

Модель	Способ отправки	Типичное время
`nano-banana-2` (Gemini 3.1 Flash Image)	`:asyncGenerateContent`	15~30 секунд
`nano-banana-pro` (Gemini 3 Pro Image)	`:asyncGenerateContent`	30~60 секунд
`gpt-image-2`, `gpt-image-1.5`, `gpt-image-2.5-*`	заголовок `Prefer: respond-async` или поле `async: true`	60~120 секунд
Другие модели генерации изображений	Как выше, по своему родному endpoint	—

Способ 1: алиас пути Gemini (рекомендуется для Gemini-клиентов)

Не нужно менять ни байта в теле запроса, заголовках или query-параметрах, только сменить суффикс действия с :generateContent на :asyncGenerateContent.

cURL

curl -X POST https://api.crazyrouter.com/v1beta/models/nano-banana-2:asyncGenerateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "draw a cat"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'

Возвращается 202:

{
  "id": "task_17754fd677574c3fbfb178ace1ee7551",
  "object": "task",
  "kind": "image",
  "model": "gemini-3.1-flash-image-preview",
  "status": "queued",
  "created_at": 1789716402
}

Возвращаемый model содержит разобранное имя базовой модели (например, gemini-3.1-flash-image-preview), такое же как и в журнале расходов; это не мешает отправлять по nano-banana-2. Референс-изображения добавляются так же, как в синхронном режиме: в parts помещаете inlineData (base64) или fileData (URL).

:asyncGenerateContent принимает только модели генерации изображений; попытка вызвать на текстовой модели вернёт 400 async mode is only available for image models. Потоковое действие :streamGenerateContent не поддерживает асинхрон.

Способ 2: OpenAI endpoint для изображений с заголовком `Prefer`

На оригинальный запрос /v1/images/generations или /v1/images/edits добавьте HTTP-заголовок Prefer: respond-async, остальное без изменений. Также можно использовать поле тела запроса "async": true (JSON) или поле формы async=true (multipart), эффект одинаковый.

curl -X POST https://api.crazyrouter.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a tiny cartoon cat sticker",
    "size": "1024x1024",
    "quality": "low",
    "n": 1
  }'

curl -X POST https://api.crazyrouter.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: respond-async" \
  -F model=gpt-image-2 \
  -F prompt="turn this into a cartoon cat sticker" \
  -F size=1024x1024 \
  -F quality=low \
  -F image=@reference.png

import requests, time

BASE = "https://api.crazyrouter.com"
H = {"Authorization": "Bearer YOUR_API_KEY"}

r = requests.post(f"{BASE}/v1/images/edits",
                  headers={**H, "Prefer": "respond-async"},
                  data={"model": "gpt-image-2", "prompt": "turn this into a cartoon cat sticker",
                        "size": "1024x1024", "quality": "low"},
                  files={"image": open("reference.png", "rb")})
task_id = r.json()["id"]

while True:
    env = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=H).json()
    if env["status"] in ("completed", "failed"):
        break
    time.sleep(3)

if env["status"] == "completed":
    print(env["result"]["data"][0]["url"])
else:
    print(env["error"])

В ответе в заголовках будет Preference-Applied: respond-async, тело идентично способу 1 (202 + ID задачи).

Запрос задачи

GET https://api.crazyrouter.com/v1/tasks/{task_id}
Authorization: Bearer YOUR_API_KEY

Запрос разрешён только для задач, отправленных текущим аккаунтом; задачи других аккаунтов всегда 404. Рекомендуется опрашивать раз в 2-3 секунды, если через 10 минут задача не завершена — считать проваленной.

Статусы

`status`	Значение
`queued`	Получена, ожидает исполнения
`running`	Генерируется
`completed`	Успешно, `result` заполнен
`failed`	Ошибка, `error` заполнен, не тарифицируется

Ответ при завершении задачи (Gemini)

result — это нативный Gemini GenerateContentResponse, только inlineData заменён на URL изображения fileData:

{
  "id": "task_17754fd677574c3fbfb178ace1ee7551",
  "object": "task",
  "kind": "image",
  "model": "gemini-3.1-flash-image-preview",
  "status": "completed",
  "progress": "100%",
  "created_at": 1789716402,
  "started_at": 1789716403,
  "completed_at": 1789716419,
  "result": {
    "candidates": [{
      "content": {
        "role": "model",
        "parts": [
          {"fileData": {"mimeType": "image/png", "fileUri": "https://media.crazyrouter.com/task-artifacts/2026/09/18/sync-image/task_17754fd677574c3fbfb178ace1ee7551-0.png"}}
        ]
      },
      "finishReason": "STOP"
    }],
    "usageMetadata": {"promptTokenCount": 15, "candidatesTokenCount": 1022, "totalTokenCount": 1037}
  },
  "error": null
}

Ответ при завершении задачи (OpenAI)

result по форме совпадает с синхронным /v1/images/*, изображение содержится в data[].url:

{
  "id": "task_b210db17cea14754818e9b965bd8a61c",
  "object": "task",
  "kind": "image",
  "model": "gpt-image-2",
  "status": "completed",
  "result": {
    "created": 1789716295,
    "data": [
      {"url": "https://media.crazyrouter.com/task-artifacts/2026/09/18/sync-image/task_b210db17cea14754818e9b965bd8a61c-0.png"}
    ],
    "usage": {"input_tokens": 77, "output_tokens": 196, "total_tokens": 273}
  },
  "error": null
}

Если вам всё же нужен base64, при запросе добавьте ?inline=true, сервер прочитает архивное изображение и вернёт его в inlineData / b64_json (не рекомендуется, большие изображения будут долго).

Ответ при ошибке

{
  "id": "task_…",
  "status": "failed",
  "result": null,
  "error": {
    "code": "provider_failed",
    "message": "upstream returned 502",
    "retryable": true
  }
}

`error.code`	Значение	Можно повторить
`validation_failed`	Параметры запроса отклонены (4xx)	Нет
`token_invalid`	API Key недействителен или модель запрещена	Нет
`insufficient_quota`	Недостаточно средств	Нет
`rate_limited`	Канал/апстрим лимитирует	Да
`provider_failed`	Сбой генерации на апстриме	Да
`timeout`	Генерация заняла более 10 минут	Да
`no_image`	Модель вернула контент, но без изображения (например, из-за блокировки безопасности), в этом случае тариф как в синхроне обычная тарификация	Нет

retryable: true означает, что можно заново создать задачу; система не будет повторять автоматически.

Идемпотентная отправка

Сетевые retry могут привести к повторной отправке одной и той же задачи. Если добавить заголовок Idempotency-Key: <любой строковый значение> при отправке, для одного аккаунта и одного Key возвращается один и тот же ID задачи (второй раз возвращается 200 вместо 202), задача не будет дублироваться и не будет двойной тарификации.

Отличия от синхронного режима

	Синхронный	Асинхронный
Ответ при отправке	Возврат изображения после генерации (20~120 секунд)	Возврат ID задачи меньше чем за 1 сек
Формат изображения	URL или base64 (по каналу)	Всегда URL
Риски таймаута соединения	Есть	Нет
Тарификация	По модели/размеру	Абсолютно идентичная; провал не тарифицируется
Маршрутизация	По возможности	Совпадает (повтор попадёт на тот же маршрут и фэйловер)
Лимиты	—	Не более 50 незавершённых задач на аккаунт, при превышении — `429`

Chat - OpenAI

Chat - Claude

Chat - Gemini

Chat - Responses API

Генерация изображений

Генерация видео

Аудио

Embeddings и rerank

Другие API

Справочник

Асинхронное создание изображений

Асинхронное создание изображений

Поддерживаемые модели

Способ 1: алиас пути Gemini (рекомендуется для Gemini-клиентов)

Способ 2: OpenAI endpoint для изображений с заголовком `Prefer`

Запрос задачи

Статусы

Ответ при завершении задачи (Gemini)

Ответ при завершении задачи (OpenAI)

Ответ при ошибке

Идемпотентная отправка

Отличия от синхронного режима

Связанные страницы

​Асинхронное создание изображений

​Поддерживаемые модели

​Способ 1: алиас пути Gemini (рекомендуется для Gemini-клиентов)

​Способ 2: OpenAI endpoint для изображений с заголовком Prefer

​Запрос задачи

​Статусы

​Ответ при завершении задачи (Gemini)

​Ответ при завершении задачи (OpenAI)

​Ответ при ошибке

​Идемпотентная отправка

​Отличия от синхронного режима

​Связанные страницы

Асинхронное создание изображений

Поддерживаемые модели

Способ 1: алиас пути Gemini (рекомендуется для Gemini-клиентов)

Способ 2: OpenAI endpoint для изображений с заголовком `Prefer`

Запрос задачи

Статусы

Ответ при завершении задачи (Gemini)

Ответ при завершении задачи (OpenAI)

Ответ при ошибке

Идемпотентная отправка

Отличия от синхронного режима

Связанные страницы