Изображения

Lovely Router поддерживает OpenAI Images API: POST /v1/images/generations и POST /v1/images/edits. Укажите в OpenAI SDK базовый URL https://lovelyrouter.com/v1 и используйте свой ключ Lovely Router. Запросы проходят в том виде, в каком их определяет OpenAI, поэтому действует справочник OpenAI по Images API с учётом ограничений ниже.

Модели#

Модели GPT Image умеют генерировать и редактировать, в том числе с референсными изображениями; z-image-turbo-nsfw-v2 только генерирует. quality не влияет на модели GPT Image 2.5 и на z-image-turbo-nsfw-v2.

Модели изображений отвечают только через Images API. При запросе к Chat Completions они возвращают 404 с указанием на /v1/images/generations. Модели GPT Image обслуживаются в группе каналов gpt-value, а z-image-turbo-nsfw-v2 — в creative-hosted, поэтому ключ, привязанный к другой группе, не может их использовать.

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

curl https://lovelyrouter.com/v1/images/generations \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor painting of a red fox in a snowy birch forest at dawn",
    "size": "1024x1024",
    "quality": "medium"
  }' | jq -r '.data[0].b64_json' | base64 --decode > fox.png

Сокращённый ответ:

{
  "created": 1792064388,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…" }],
  "background": "auto",
  "model": "gpt-image-2",
  "output_format": "png",
  "quality": "medium",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 19,
    "input_tokens_details": { "text_tokens": 19, "image_tokens": 0 },
    "output_tokens": 1756,
    "output_tokens_details": { "image_tokens": 1756, "text_tokens": 0 },
    "total_tokens": 1775
  }
}

Изображения всегда возвращаются в base64 в поле b64_json. response_format: "url" игнорируется. Обычно изображение создаётся от 40 секунд до 2 минут плюс время ожидания в очереди, поэтому задайте HTTP-клиенту тайм-аут не меньше десяти минут (шлюз отвечает в пределах девяти). PNG размером 3840×2160 весит около 14 МБ, или 18 МБ в base64. Чтобы отправить изображение и забрать результат позже, не удерживая соединение, используйте задания на изображения.

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

• size: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160 или любой WIDTHxHEIGHT, где обе стороны кратны 16, длинная сторона не больше 3840 пикселей и не больше чем в три раза длиннее короткой, а общее число пикселей — от 655 360 до 8 294 400. auto оставляет выбор модели.
• quality: low, medium, high или auto (по умолчанию). Цена одинакова для любого качества.
• output_format: png (по умолчанию), jpeg или webp. output_compression (от 0 до 100) применяется к jpeg и webp.
• background: transparent работает с png и webp.

Несколько изображений#

Задайте n от 1 до 10, чтобы получить несколько изображений по одному промпту за один запрос. Это работает и для генерации, и для редактирования. Изображения возвращаются вместе в data.

result = client.images.generate(
    model="gpt-image-2",
    prompt="A watercolor painting of a red fox in a snowy birch forest at dawn",
    n=4,
)
for i, image in enumerate(result.data):
    with open(f"fox-{i + 1}.png", "wb") as f:
        f.write(base64.b64decode(image.b64_json))

• Каждое изображение стоит как одно изображение, так что четыре стоят в четыре раза больше. При отправке резервируется цена всех n, а платите вы только за полученные изображения.
• Изображения создаются за минимальное число вызовов модели, которое позволяет канал. С моделями GPT Image n: 4 обычно занимает примерно столько же времени, сколько одно изображение. Размещённые модели создают их по очереди на одном GPU.
• Если часть изображений создать не удалось, вы получите те, что получились, и заплатите только за них. У задания на изображения тогда будет status: "succeeded" и error.type: "incomplete" с сообщением о том, сколько изображений не хватает.
• Каждое изображение учитывается в лимите 20 изображений, которые аккаунт может одновременно держать в очереди или в генерации.

Редактирование изображения#

Редактировать умеет каждая модель, включая GPT Image 2.5. Отправьте одно или несколько изображений и, при желании, mask как multipart/form-data на POST /v1/images/edits. Модель, промпт и остальные параметры работают так же, как при генерации. Чтобы дать модели несколько исходных изображений, см. референсные изображения.

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2 \
  -F image=@fox.png \
  -F prompt="Make it night with a full moon" \
  -F quality=medium | jq -r '.data[0].b64_json' | base64 --decode > fox-night.png

Для GPT Image 2.5 укажите в model значение gpt-image-2.5-flare или gpt-image-2.5-sunburst и не передавайте quality — эти модели его игнорируют:

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2.5-flare \
  -F image=@fox.png \
  -F prompt="Make it night with a full moon" | jq -r '.data[0].b64_json' | base64 --decode > fox-night.png

Редактирование стоит столько же, сколько генерация.

Референсные изображения#

Дайте модели до 16 исходных изображений — например, товар, логотип, человека или стиль — и укажите в промпте, что взять из каждого. Отправляйте каждое как файл image[]. SDK OpenAI делают это сами, если передать список.

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F model=gpt-image-2.5-flare \
  -F "image[]=@mug.png" \
  -F "image[]=@table.jpg" \
  -F prompt="The mug from the first image on the wooden table from the second, morning light" \
  | jq -r '.data[0].b64_json' | base64 --decode > mug-on-table.png

Можно также отправить JSON и передать изображения как URL или base64 data: URL:

curl https://lovelyrouter.com/v1/images/edits \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "The same character, now waving, flat illustration",
    "images": [
      {"image_url": "https://example.com/character.png"},
      {"image_url": "data:image/png;base64,iVBORw0KGgo..."}
    ]
  }' | jq -r '.data[0].b64_json' | base64 --decode > waving.png

• image также принимает один URL или список URL, а mask — один URL. Изображения по file_id не поддерживаются.
• URL скачиваются один раз, в момент поступления запроса. Они должны быть публичными и отвечать в течение 20 секунд.
• Входные изображения — PNG, JPEG или WebP, всего до 50 МБ.
• Запрос к POST /v1/images/generations с входными изображениями обрабатывается как редактирование.

Цены#

Модели GPT Image стоят $0.04 за изображение, а z-image-turbo-nsfw-v2 — $0.03, одинаково для любого размера и качества, как при генерации, так и при редактировании. Объект usage в ответе носит справочный характер и на цену не влияет. Применяется множитель группы каналов (×1.00 для gpt-value и creative-hosted).

GET /v1/models показывает текущую цену в поле pricing.per_image в долларах США. Каждый вызов отображается в Логах вместе с суммой списания.

При отправке изображения его цена резервируется на балансе и освобождается, когда изображение готово. С n резервируется цена всех n изображений, а платите вы только за полученные. Списания нет, если запрос отклонён, задание отменено или изображение не создано. Сгенерированное изображение оплачивается, даже если ваш клиент отключился до его получения.

Как запросы ставятся в очередь#

Каждый запрос на изображение встаёт в очередь и запускается, как только освобождаются мощности для изображений, поэтому всплеск запросов ждёт своей очереди, а не завершается ошибкой. POST /v1/images/generations и POST /v1/images/edits держат соединение, пока изображение не будет готово, до 9 минут. Если к этому времени оно не готово, они отвечают 504 с идентификатором задания в заголовке x-lovely-image-job и в сообщении; генерация продолжается, изображение оплачивается по готовности, и его можно забрать через GET /v1/images/jobs/{id}.

• У каждого аккаунта может быть до 20 изображений в очереди или в генерации одновременно, считая каждое изображение запроса с n. Запрос, который превысил бы 20, возвращает 429, пока часть не завершится.
• Изображение, которое не удалось запустить в течение 30 минут, завершается ошибкой 429, и ничего не списывается.
• В каждом ответе есть заголовок x-lovely-request-id (идентификатор задания), совпадающий с вызовом в Логах.

Задания на изображения#

Задания на изображения — это те же запросы, но без удержания соединения: отправьте задание, а затем опрашивайте его обычным или длинным опросом (long polling). Используйте их для пакетов или когда клиент не может ждать несколько минут.

curl https://lovelyrouter.com/v1/images/jobs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "A watercolor painting of a red fox in a snowy birch forest at dawn", "size": "1536x1024"}'

Тело принимает те же поля, что и POST /v1/images/generations. Входные изображения делают задание редактированием, как в POST /v1/images/edits: multipart/form-data с файлами image или images в JSON. Добавьте wait (от 0 до 300 секунд, в теле или как ?wait=), чтобы дождаться задания перед ответом: вы получите 200, если оно успело завершиться, иначе 202.

Затем дождитесь результата. wait удерживает запрос, пока задание не завершится или не истечёт время:

curl "https://lovelyrouter.com/v1/images/jobs/img_8c1f0e2a9b7d4f3e6a5c2b1d?wait=60" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

У завершённого задания status: "succeeded", его charge_usd и result с полями изображения url, content_type, bytes, size и usage. result.images перечисляет все изображения задания, у каждого свои url, content_type и bytes: при n больше 1 первое изображение доступно по /content, а остальные — по /content/1, /content/2 и так далее. Скачайте файл изображения по этому URL с тем же ключом:

curl -o fox.png https://lovelyrouter.com/v1/images/jobs/img_8c1f0e2a9b7d4f3e6a5c2b1d/content \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Песочница использует задания на изображения: переключите её в режим Изображения, чтобы пробовать промпты и редактирование без кода.

Ограничения#

• До 10 изображений на запрос с n. Если нужно больше, отправьте несколько запросов или заданий.
• Без потоковой передачи. stream: true возвращает 400. Промежуточные изображения пока недоступны.
• Без вариаций. POST /v1/images/variations (только DALL·E 2) возвращает 404.
• На отправку изображений действует лимит запросов в минуту вашего ключа. В очереди или в генерации одновременно может быть до 20 изображений на аккаунт.