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

ZvenoAI предоставляет доступ к моделям генерации изображений через два API:

Для одиночной генерации начинайте с POST /v1/images. Используйте chat completions, если изображение должно стать частью диалога или выбранная модель предоставляет генерацию через чат-контракт.

Поиск подходящей модели

В каталоге моделей выберите выходную модальность image. Карточка показывает slug модели, входные и выходные модальности, провайдеров и цену.

После выбора модели проверьте параметры активных провайдеров через GET /v1/models/{vendor}/{model}/providers. Поле supported_parameters служит подсказкой о совместимости, но может не описывать все провайдерские настройки.

Набор моделей и их возможностей меняется. Не закрепляйте список моделей или допустимые параметры в клиентском коде.

Image API: POST /v1/images

Image API использует единое тело запроса независимо от провайдера. Обязательны только model и prompt.

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

import base64
import os
import requests

response = requests.post(
    "https://api.zveno.ai/v1/images",
    headers={"Authorization": f"Bearer {os.environ['ZVENO_API_KEY']}"},
    json={
        "model": "openai/gpt-image-1",
        "prompt": "Акварельный маяк на скалистом берегу",
    },
)
response.raise_for_status()

image = response.json()["data"][0]["b64_json"]
with open("output.png", "wb") as file:
    file.write(base64.b64decode(image))

import fs from 'node:fs'

const response = 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: 'Акварельный маяк на скалистом берегу',
  }),
})

if (!response.ok) throw new Error(await response.text())

const result = await response.json()
fs.writeFileSync('output.png', Buffer.from(result.data[0].b64_json, '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": "Акварельный маяк на скалистом берегу"
  }' \
  | jq -r '.data[0].b64_json' \
  | base64 -d > output.png

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

Image API возвращает изображения в data[].b64_json без префикса data URL:

{
  "created": 1784764800,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg..."
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 0,
    "total_tokens": 18,
    "cost": 0.04
  }
}

Поле media_type присутствует, когда формат результата нужно указать явно, например для SVG.

Размер, качество и формат

Параметры результата передаются на верхнем уровне:

{
  "model": "bytedance-seed/seedream-4.5",
  "prompt": "Панорамный вид города у моря",
  "resolution": "2K",
  "aspect_ratio": "16:9",
  "n": 1
}

Не передавайте одновременно конфликтующие варианты размера. Например, точный size может быть несовместим с выбранными resolution и aspect_ratio.

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

Передайте исходные изображения в input_references. Элемент массива — строка с data URL или объект { "url": "..." }.

Data URL принимают все модели, поэтому это основной способ:

{
  "model": "openai/gpt-image-1",
  "prompt": "Сохрани композицию, но замени дневное освещение на закатное",
  "input_references": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."]
}

HTTP(S)-ссылку принимают не все модели. Если модель её не поддерживает, API вернёт ошибку 400:

{
  "model": "openai/gpt-image-1",
  "prompt": "Сохрани композицию, но сделай сцену похожей на акварель",
  "input_references": [{ "url": "https://example.com/source.png" }]
}

Держите суммарный размер референсов в пределах 8 МБ: у части моделей это жёсткий предел.

Число референсов и поддерживаемые MIME-типы зависят от модели.

Генерация в Chat Completions

Некоторые мультимодальные модели возвращают изображение прямо в ответе POST /v1/chat/completions. Добавьте "image" в modalities, а настройки результата передайте в верхнеуровневом image_config.

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

Text-to-image

Ниже — пример для google/gemini-3-pro-image-preview. У другой модели состав image_config может отличаться.

{
  "model": "google/gemini-3-pro-image-preview",
  "messages": [
    {
      "role": "user",
      "content": "Нарисуй маяк на скалистом берегу на закате"
    }
  ],
  "modalities": ["image", "text"],
  "image_config": {
    "aspect_ratio": "4:5",
    "image_size": "4K"
  }
}

Для этой модели image_size принимает 1K, 2K и 4K; значение чувствительно к регистру. Передавайте имя поля в snake_case. imageSize, generationConfig, width и height не относятся к контракту chat completions.

Image-to-image

Входное изображение передаётся в messages[].content отдельной частью image_url. Сначала размещайте текстовую инструкцию, затем изображения.

Полный запрос с HTTP(S)-ссылкой:

{
  "model": "google/gemini-3-pro-image-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Сохрани композицию, но замени дневное освещение на закатное"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/source.png"
          }
        }
      ]
    }
  ],
  "modalities": ["image", "text"],
  "image_config": {
    "aspect_ratio": "4:5",
    "image_size": "2K"
  }
}

Для локального или закрытого файла замените URL в том же поле:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

Обычно принимаются image/png, image/jpeg, image/webp и image/gif, но окончательный набор определяет модель.

Изображения в ответе

Chat completions возвращает изображения в choices[].message.images как data URL:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Готово.",
        "images": [
          {
            "url": "data:image/png;base64,iVBORw0KGgo..."
          }
        ]
      }
    }
  ]
}

Не закладывайте в клиент единую трактовку элементов массива images. В зависимости от модели это могут быть независимые результаты, промежуточные изображения или финальный рендер. Обрабатывайте массив по правилам выбранной модели.

const finalGeminiImage = response.choices[0].message.images.at(-1)

final_gemini_image = response["choices"][0]["message"]["images"][-1]

Streaming

Формат потока зависит от выбранного API:

• POST /v1/images использует события image_generation.partial_image, image_generation.completed и error;
• POST /v1/chat/completions передаёт изображения в choices[].delta.images и завершает поток маркером data: [DONE].

Не все модели поддерживают streaming или промежуточные изображения. Проверяйте эту возможность перед запросом и сохраняйте результат из завершающего события выбранного API.

Биллинг

Стоимость зависит от модели, провайдера и параметров результата: разрешения, качества, числа изображений и референсов. Итоговое списание смотрите в /v1/credits и /v1/activity.

Если запрос завершается ошибкой до получения результата, зарезервированная сумма возвращается. Подробнее — в руководстве по ошибкам.

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

Не смешивайте контракты

Дополнительные материалы

• OpenRouter: Image API — общий контракт и параметры моделей.
• OpenRouter: image inputs — URL и base64 в мультимодальных сообщениях.
• Google Gemini API: image generation — параметры и особенности моделей Gemini.
• Streaming (SSE) — обработка потоковых ответов.
• Выбор моделей — фильтрация каталога и настройка провайдера.