Images

Используйте POST /v1/images/generations для OpenAI-style генерации изображений и POST /v1/images/edits для OpenAI-style редактирования изображений.

POST https://api.rout.my/v1/images/generations

Запрос

curl https://api.rout.my/v1/images/generations \
  -H "Authorization: Bearer $ROUTMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/image-model-id",
    "prompt": "A clean product photo of a translucent blue cube on a white table",
    "n": 1,
    "image_config": {
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'

Поля запроса

Поле	Тип	Обязательное	Примечания
model	string	Да	Точный image model ID из /v1/models.
prompt	string	Да	Текстовое описание изображения.
response_format	string	Нет	url (по умолчанию) или b64_json; формат выдачи нормализуется GoRouter.
n	integer	Нет	Количество изображений. Если опущено, используется поведение провайдера.
size	string	Нет	OpenAI-style size, если модель поддерживает.
quality	string	Нет	Quality hint, если модель поддерживает.
style	string	Нет	Style hint, если модель поддерживает.
user	string	Нет	Принимается для совместимости, но не пробрасывается в upstream.
image_config	object	Нет	Provider-neutral настройки изображения.

image_config

Поле	Тип	Примечания
aspect_ratio	string	Частые значения: 1:1, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4, 21:9.
image_size	string	Частые значения: 1K, 2K, 4K. Значение пробрасывается провайдеру, если поддерживается.

Ответ

Для /v1/images/generations по умолчанию (response_format: "url") изображение возвращается в data[].url. GoRouter при необходимости скачивает изображение, проверяет кодировку и тип и формирует data:image/png;base64,... (либо JPEG/WebP/GIF по фактическим байтам). Исходные HTTP(S)-ссылки upstream клиенту не возвращаются.

{
  "created": 1744000000,
  "data": [
    {
      "url": "data:image/png;base64,iVBORw0KGgo...",
      "revised_prompt": "A clean product photo of a translucent blue cube..."
    }
  ]
}

При явном response_format: "b64_json" возвращается чистый base64 без префикса data::

{
  "created": 1744000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

data[].url можно напрямую использовать как src изображения. Формат b64_json нужно декодировать или самостоятельно добавить префикс для отображения. response_format обрабатывается локально и не передаётся upstream. Повреждённые inline-данные возвращают 502 без повторной генерации. Формат streaming image edits не меняется.

Image edits

Используйте POST /v1/images/edits, когда модель должна изменить одно или несколько входных изображений.

POST https://api.rout.my/v1/images/edits

Для JSON-запросов используйте images как массив. Multipart-запросы могут использовать OpenAI-style file fields image.

curl https://api.rout.my/v1/images/edits \
  -H "Authorization: Bearer $ROUTMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/image-edit-model-id",
    "prompt": "Keep the product, replace the background with a clean studio gradient",
    "images": [
      {
        "image_url": "https://example.com/input.png"
      }
    ],
    "n": 1,
    "size": "1024x1024"
  }'

Частые поля для edits: model, prompt, images, image, mask, n, size, quality, background, input_fidelity, moderation, output_compression, output_format, partial_images, stream. Поле user принимается для совместимости, но не пробрасывается в upstream.

Расход квоты

Image generation и image edits списывают квоту по количеству выходных изображений, умножая на token_multiplier модели:

Requested size	Base quota units per image
empty, 1K, 2K или другие non-4K значения	5,000
4K	12,500

Provider-reported usage.total_tokens может использоваться внутри, если доступен, но он не может уменьшить billable base ниже floor за output image. Эффективная база:

max(provider_usage.total_tokens, output_images * base_quota_units_per_image)

Для /v1/images/edits default floor — 5,000 quota units за каждое выходное изображение. Public response может содержать provider usage, если upstream его вернул, но private billing metadata не раскрывается.

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

Некоторые image-capable chat models используют /v1/chat/completions с modalities: ["image", "text"]. Формат описан в Chat Completions.

Редактирование изображений использует ту же проверку выдачи: b64_json по умолчанию или data URI при response_format: "url". Потоковые ответы сохраняют события изображений и usage; метаданные маршрутизации и исходные ошибки upstream удаляются.