POST /images/generations

Генерация изображений через эндпоинт /images/generations API LLMost, совместимый с OpenAI Images API.

Эндпоинт генерации изображений позволяет создавать и редактировать изображения любыми image-моделями каталога LLMost через единый интерфейс. Он совместим с OpenAI Images API и дополнен расширениями LLMost — управлением соотношением сторон, разрешением и редактированием по картинкам-референсам.

Основная информация

Эндпоинт: POST https://llmost.ru/api/v1/images/generations

Аутентификация — API-ключ LLMost в заголовке Authorization: Bearer llmost_... (см. Аутентификация).

Совместимость с OpenAI SDK

Существующий код на официальных SDK OpenAI работает без изменений: поменяйте base_url на https://llmost.ru/api/v1, подставьте ключ LLMost и вызывайте images.generate(). Расширения LLMost — опциональные поля, которые OpenAI-клиенты просто не отправляют.

Генерацию поддерживают модели с выходной модальностью image — ищите их в каталоге моделей. Списание происходит по фактической стоимости генерации у провайдера; перед запуском проверяется оценочная стоимость с учётом выбранных параметров и количества изображений.

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

Базовый пример

const response = await fetch('https://llmost.ru/api/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <LLMOST_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'google/gemini-3-pro-image-preview-20251120',
    prompt: 'Кот-космонавт в открытом космосе, фотореализм',
  }),
});

const data = await response.json();
// Изображение в base64 — сохраните или покажите пользователю
console.log(data.data[0].b64_json.slice(0, 50));

Обязательные параметры

prompt

Тип: string

Текстовое описание изображения. Чем конкретнее описание (стиль, композиция, освещение), тем предсказуемее результат.

{
  "prompt": "Уютная кофейня в дождливый вечер, вид с улицы, тёплый свет из окон, акварель"
}

model

Тип: string

Слаг модели из каталога, например google/gemini-3-pro-image-preview-20251120. Полный список — на странице Модели.

{
  "model": "google/gemini-3-pro-image-preview-20251120"
}

Модель обязательна

В отличие от /chat/completions, у генерации изображений нет модели по умолчанию: запрос без model вернёт ошибку 400 MODEL_REQUIRED. Текстовая модель в этом эндпоинте тоже не сработает — вернётся 400 MODEL_NOT_IMAGE_CAPABLE.

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

n

Тип: integer • Диапазон: [1, 10] • По умолчанию: 1

Число изображений за один запрос. Часть моделей игнорирует n и возвращает одно изображение — фактическое количество смотрите по длине массива data в ответе.

{
  "n": 4
}

size

Тип: string

Размер изображения в формате OpenAI, например "1024x1024". Значение "auto" означает размер по умолчанию провайдера. Для точного управления кадром удобнее расширения aspect_ratio и resolution.

{
  "size": "1024x1024"
}

quality

Тип: string

Качество генерации: low / medium / high — проверяется по возможностям модели; auto — по умолчанию провайдера; другие значения (например hd) передаются провайдеру как есть.

{
  "quality": "high"
}

response_format

Тип: string • Значения: b64_json | url • По умолчанию: b64_json

Формат изображений в ответе: b64_json — base64 прямо в JSON, url — прямая ссылка на файл в хранилище LLMost. Подробнее — в разделе Структура ответа.

{
  "response_format": "url"
}

output_format

Тип: string • Значения: png | jpeg | webp

Формат файла изображения (для моделей, которые это поддерживают).

{
  "output_format": "webp"
}

background

Тип: string • Значения: transparent | opaque | auto

Прозрачный или непрозрачный фон — для моделей с поддержкой прозрачности (например, gpt-image).

{
  "background": "transparent"
}

seed

Тип: integer

Зерно генерации для воспроизводимости результата — там, где модель это поддерживает. Одинаковые prompt + seed дают близкие или идентичные изображения.

{
  "seed": 42
}

Игнорируемые и неизвестные поля

Поля OpenAI user, style, moderation, output_compression принимаются и игнорируются, а неизвестные поля не приводят к ошибке — запрос от любого drop-in клиента не сломается.

Расширения LLMost

aspect_ratio

Тип: string

Соотношение сторон в формате "ширина:высота", например "16:9", "1:1", "9:16". Доступные значения зависят от модели.

{
  "aspect_ratio": "16:9"
}

resolution

Тип: string • Значения: 512 | 1K | 2K | 4K

Класс разрешения изображения. Доступные значения зависят от модели; от разрешения обычно зависит и цена генерации.

{
  "resolution": "2K"
}

input_references

Тип: string[] • Максимум: 16 элементов

Массив URL картинок-референсов. Превращает генерацию в редактирование: модель опирается на переданные изображения — правки, стилизация, комбинирование. Отдельный эндпоинт /images/edits не нужен.

{
  "prompt": "Сделай фон синим",
  "input_references": ["https://example.com/cat.png"]
}

Если возможности модели описаны в каталоге и переданное значение aspect_ratio / resolution / quality не поддерживается, вернётся ошибка 400 с указанием допустимых значений или ожидаемого формата. Для моделей без описанных возможностей параметры передаются провайдеру как есть — неподдерживаемые значения он молча приводит к ближайшим.

Структура ответа

Успешный ответ

{
  "created": 1753612800,
  "data": [
    { "b64_json": "iVBORw0KGgo..." }
  ],
  "usage": {
    "input_tokens": 10,
    "output_tokens": 1000,
    "total_tokens": 1010,
    "cost": 26.8
  }
}

Поля ответа

data

Массив сгенерированных изображений. Каждый элемент содержит одно из полей:

b64_json — изображение в base64 (режим по умолчанию)
url — прямая ссылка на файл в хранилище LLMost (при response_format: "url"). Ссылка постоянная. Если загрузка в хранилище не удалась, элемент вернётся как b64_json — изображение вы получите в любом случае

usage

Информация об использовании и списании.

input_tokens — токены запроса (если провайдер их сообщает)
output_tokens — токены результата, включая image-токены
total_tokens — суммарно
cost — расширение LLMost: фактически списанная сумма в рублях, с учётом выбранных параметров и количества изображений

Примеры кода

Python с OpenAI SDK

Расширения LLMost передаются через extra_body:

import base64

from openai import OpenAI

client = OpenAI(
    base_url="https://llmost.ru/api/v1",
    api_key="ВАШ_API_КЛЮЧ",
)

image = client.images.generate(
    model="google/gemini-3-pro-image-preview-20251120",
    prompt="Кот-космонавт в открытом космосе, фотореализм",
    extra_body={"aspect_ratio": "16:9", "resolution": "2K"},
)

with open("cat.png", "wb") as f:
    f.write(base64.b64decode(image.data[0].b64_json))

TypeScript с OpenAI SDK

Расширения LLMost не описаны в типах SDK — передайте их через приведение типа:

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://llmost.ru/api/v1',
  apiKey: process.env.LLMOST_API_KEY,
});

const image = await openai.images.generate({
  model: 'google/gemini-3-pro-image-preview-20251120',
  prompt: 'Кот-космонавт в открытом космосе, фотореализм',
  aspect_ratio: '16:9',
  resolution: '2K',
} as OpenAI.ImageGenerateParams);

const buffer = Buffer.from(image.data[0].b64_json!, 'base64');

cURL

curl https://llmost.ru/api/v1/images/generations \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-3-pro-image-preview-20251120",
    "prompt": "Кот-космонавт в открытом космосе, фотореализм",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

Go

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "os"

    "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("ВАШ_API_КЛЮЧ")
    config.BaseURL = "https://llmost.ru/api/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateImage(
        context.Background(),
        openai.ImageRequest{
            Model:          "google/gemini-3-pro-image-preview-20251120",
            Prompt:         "Кот-космонавт в открытом космосе, фотореализм",
            ResponseFormat: openai.CreateImageResponseFormatB64JSON,
        },
    )
    if err != nil {
        fmt.Printf("Ошибка: %v\n", err)
        return
    }

    data, _ := base64.StdEncoding.DecodeString(resp.Data[0].B64JSON)
    os.WriteFile("cat.png", data, 0o644)
}

Продвинутые возможности

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

Передайте исходные изображения в input_references, а в prompt опишите правку:

{
  "model": "google/gemini-3-pro-image-preview-20251120",
  "prompt": "Замени фон на закатное небо, сохрани персонажа без изменений",
  "input_references": ["https://example.com/hero.png"]
}

Итеративное редактирование

Связка с response_format: "url" даёт цикл правок без перекачивания base64: результат каждого шага возвращается ссылкой, которую вы передаёте в input_references следующего запроса.

// Шаг 1: генерация
const first = await generate({
  prompt: 'Логотип кофейни, минимализм',
  response_format: 'url',
});

// Шаг 2: правка результата по ссылке
const second = await generate({
  prompt: 'Добавь тёплую кремовую палитру',
  response_format: 'url',
  input_references: [first.data[0].url],
});

Детерминированная генерация

Фиксируйте seed, чтобы воспроизводить результат или сравнивать модели на одинаковых условиях:

{
  "prompt": "Иллюстрация горного пейзажа в стиле линогравюры",
  "seed": 1337
}

Поддержка параметров моделями

Набор поддерживаемых параметров (aspect_ratio, resolution, quality, n, seed, background) различается между моделями. Доступные значения указаны на странице модели в каталоге.

Обработка ошибок

Коды ошибок

400 — неверный запрос: битый JSON, отсутствует prompt или model (MODEL_REQUIRED), модель не найдена (MODEL_NOT_FOUND), модель не генерирует изображения (MODEL_NOT_IMAGE_CAPABLE), недопустимые параметры (IMAGE_PARAMS_INVALID)
401 — недействительный или отсутствующий API-ключ
402 — недостаточно средств на балансе (в ответе есть currentBalance)
502 — сбой генерации на стороне провайдера; списания при этом не происходит

Пример ответа с ошибкой

{
  "error": {
    "message": "aspect_ratio 3:7 not supported (allowed: 1:1, 16:9)",
    "type": "invalid_request",
    "code": "IMAGE_PARAMS_INVALID"
  }
}

Обработка ошибок в коде

const response = await fetch('https://llmost.ru/api/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ model, prompt }),
});

if (!response.ok) {
  const { error } = await response.json();

  if (response.status === 402) {
    console.log(`Пополните баланс: осталось ${error.currentBalance} ₽`);
  } else if (response.status === 502) {
    // Провайдер сбоит, деньги не списаны — можно повторить
    console.log('Генерация не удалась, повторите попытку');
  } else {
    // 400: исправьте запрос, повторять без изменений бессмысленно
    console.error(`${error.code}: ${error.message}`);
  }
}

См. Ошибки для общего формата ошибок API.

Лучшие практики

1. Проверяйте возможности модели

Перед использованием aspect_ratio / resolution / quality сверьтесь со страницей модели в каталоге: для моделей с описанными возможностями недопустимое значение вернёт 400, а «4K у всех подряд» — частая причина ошибок.

2. Увеличьте таймаут клиента

Генерация синхронная и занимает от нескольких секунд до минуты (высокие разрешения — дольше). Дефолтных таймаутов многих HTTP-клиентов не хватает:

const openai = new OpenAI({
  baseURL: 'https://llmost.ru/api/v1',
  apiKey: process.env.LLMOST_API_KEY,
  timeout: 120_000, // 2 минуты
});

Ознакомьтесь с Аутентификацией для безопасной работы с ключами
Изучите Обработку ошибок — общий формат для всего API
Выберите подходящую image-модель в каталоге моделей
Для текстовых задач используйте POST /chat/completions

POST /images/generations

На этой странице