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

Картинку можно получить двумя путями. Оба принимают текстовый промпт, оплачиваются в рублях по цене выбранной модели за изображение и возвращают результат в base64.

Выделенный роут: POST /v1/images

Синхронный роут: отправляете промпт и параметры — в ответ приходит массив картинок. Форма запроса и ответа совместима с OpenRouter.

Быстрый старт

import os, base64, requests

resp = requests.post(
    "https://api.zveno.ai/v1/images",
    headers={"Authorization": f"Bearer {os.environ['ZVENO_API_KEY']}"},
    json={
        "model": "openai/gpt-image-1",
        "prompt": "Изометричная иллюстрация уютной кофейни, мягкий свет",
        "size": "1024x1024",
        "quality": "high",
        "background": "transparent",
        "output_format": "png",
    },
).json()

b64 = resp["data"][0]["b64_json"]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

import fs from 'node:fs'

const resp = await fetch('https://api.zveno.ai/v1/images', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ZVENO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-image-1',
    prompt: 'Изометричная иллюстрация уютной кофейни, мягкий свет',
    size: '1024x1024',
    quality: 'high',
    background: 'transparent',
    output_format: 'png',
  }),
}).then((r) => r.json())

const b64 = resp.data[0].b64_json
fs.writeFileSync('output.png', Buffer.from(b64, 'base64'))

curl -sS https://api.zveno.ai/v1/images \
  -H "Authorization: Bearer $ZVENO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "Изометричная иллюстрация уютной кофейни, мягкий свет",
    "size": "1024x1024",
    "quality": "high"
  }' | jq -r '.data[0].b64_json' | base64 -d > output.png

Параметры запроса

Все параметры передаются на верхнем уровне тела. Какие из них примет конкретная модель — зависит от её supported_parameters (см. Поиск моделей); неподдерживаемый параметр модель отклонит ошибкой 400, а не проигнорирует молча.

Формат ответа

{
  "created": 1730000000,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUg...", "media_type": "image/png" }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 0, "total_tokens": 12 }
}

• data[].b64_json — содержимое картинки в base64 без префикса data: (в отличие от chat completions). Декодируйте напрямую в файл.
• media_type — тип содержимого; присутствует, когда он отличается от растрового png (например, svg у части моделей).
• usage — счётчики токенов запроса. Итоговое списание в рублях смотрите в /v1/credits и /v1/activity.

Стриминг

С параметром stream: true (у моделей, которые поддерживают потоковую генерацию) картинка приходит серией SSE-событий: несколько промежуточных кадров, затем финальный.

• image_generation.partial_image — промежуточный кадр: { "partial_image_index": 0, "b64_json": "..." }
• image_generation.completed — готовая картинка: { "b64_json": "...", "created": ..., "usage": {...} }
• image_generation.error — ошибка генерации
• завершается стандартным data: [DONE]

import os, json, base64, requests

with requests.post(
    "https://api.zveno.ai/v1/images",
    headers={"Authorization": f"Bearer {os.environ['ZVENO_API_KEY']}"},
    json={
        "model": "openai/gpt-image-1",
        "prompt": "Неоновый киберпанк-переулок под дождём",
        "stream": True,
    },
    stream=True,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[6:]
        if payload == b"[DONE]":
            break
        event = json.loads(payload)
        if event.get("type") == "image_generation.completed":
            with open("output.png", "wb") as f:
                f.write(base64.b64decode(event["b64_json"]))

Через chat completions

Мультимодальные модели умеют возвращать картинку прямо в ответе POST /v1/chat/completions — как часть обычного диалога. От текстового запроса он отличается двумя вещами: в modalities добавляется "image", а картинка приходит в choices[].message.images.

Быстрый старт

import os, base64, requests

resp = requests.post(
    "https://api.zveno.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['ZVENO_API_KEY']}"},
    json={
        "model": "google/gemini-2.5-flash-image",
        "messages": [{"role": "user", "content": "Закат над горами, акварельная стилистика"}],
        "modalities": ["image", "text"],
        "image_config": {"aspect_ratio": "16:9"},
    },
).json()

image = resp["choices"][0]["message"]["images"][0]["url"]
# image = "data:image/png;base64,iVBORw0KGgo..."
_, b64 = image.split(",", 1)
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

curl -sS https://api.zveno.ai/v1/chat/completions \
  -H "Authorization: Bearer $ZVENO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-image",
    "messages": [{"role":"user","content":"Закат над горами, акварельная стилистика"}],
    "modalities": ["image","text"],
    "image_config": {"aspect_ratio": "16:9"}
  }' | jq -r '.choices[0].message.images[0].url' \
  | sed 's|^data:image/[^;]*;base64,||' \
  | base64 -d > output.png

Параметры

image_config — открытый набор: незнакомые ключи не отбрасываются, а передаются модели как есть. Что именно модель учтёт — определяется её возможностями.

Формат ответа

Ответ — стандартный chat completion, но у message появляется массив images. Каждый элемент — { "url": "data:image/png;base64,..." } (здесь картинка приходит как data URL, с префиксом).

{
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Готово — закат над горами в акварельной стилистике.",
        "images": [{ "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." }]
      }
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 0, "total_tokens": 12 }
}

content — текстовый комментарий модели (может быть пустым). usage.completion_tokens у многих моделей равен 0: картинки тарифицируются по фиксированной цене за изображение, а не по токенам.

Редактирование по референсам

И на /v1/images, и в chat completions можно передать исходные изображения в input_references — для редактирования или генерации по образцу (image-to-image). Ссылки — публичные URL или data URL. Сколько референсов принимает модель — часть её возможностей (у одних один-два, у других больше).

{
  "model": "openai/gpt-image-1",
  "prompt": "Замени фон на зимний пейзаж, стиль сохрани",
  "input_references": ["https://example.com/source.png"]
}

Поиск моделей и supported_parameters

Модели с генерацией картинок отмечены модальностью image в списке output_modalities. Каждая модель понимает свой набор параметров, поэтому перед запросом свериться с её возможностями.

Соотношения сторон

aspect_ratio у Gemini-семейства принимает фиксированный набор значений: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (у отдельных моделей набор шире). Каждому значению соответствует свой размер в пикселях, привязанный к ступени разрешения модели.

Биллинг

Стоимость изображения в рублях фиксирована для пары «модель + параметры» и списывается после завершения генерации. В отличие от текста, usage.completion_tokens часто нулевой: платите за изображение, не за токены. При запросе нескольких картинок (n > 1) списание — за фактическое количество.

Резервирование двухфазное: перед обращением к провайдеру со счёта резервируется оценочная стоимость, после генерации резерв заменяется фактической. При ошибке провайдера резерв возвращается автоматически — в том числе кредит подписки. Итоговую сумму по каждому запросу видно в /v1/credits и /v1/activity.

Решение типичных проблем

Что дальше

• Ввод изображений (Vision) — как передавать картинки на вход модели.
• Streaming (SSE) — подробнее о потоковых ответах.
• Выбор моделей — фильтрация каталога и настройка выбора провайдера.
• Каталог моделей — актуальный список моделей с генерацией картинок.
• Генерация видео — если нужен движущийся результат вместо статичной картинки.