Image API — генерация и редактирование

Вызывайте gpt-image-2 для генерации и редактирования изображений через ZetaAPI. Совместимо с OpenAI Images — примеры curl / Python / Node, multipart-редактирование, размеры вывода, оплата и таймауты.

Обновлено 2026-07-26

Эндпоинты изображений ZetaAPI полностью совместимы с OpenAI Images API — используйте свой существующий API-ключ, чтобы генерировать и редактировать изображения через gpt-image-2, без изменений в SDK. Чтобы сначала попробовать в браузере, откройте Playground изображений в консоли; здесь описан вызов из кода.

Base URL и аутентификация

Запросы на генерацию изображений идут на отдельный домен для изображений:

https://image.zetaapi.ai

Каждый запрос содержит Authorization: Bearer sk-xxxxx (тот же ключ, что и для чата).

Почему у изображений отдельный домен: генерация изображения — это длительный непотоковый запрос, ожидание отрисовки на стороне провайдера занимает до 240 секунд. Основной домен api.zetaapi.ai работает через CDN, который разрывает соединение примерно на 120-й секунде. Вы получаете ошибку, но изображение уже сгенерировано на стороне провайдера, и оно тарифицируется. Домен для изображений подключается напрямую к источнику и не имеет этого ограничения — не выполняйте автоматических повторов генерации через основной домен.

Этот домен обслуживает только /v1/images/generations и /v1/images/edits. Всё остальное — включая описанную ниже генерацию высокого разрешения через Gemini, которая идёт через /v1/chat/completions, — по-прежнему использует https://api.staging.cosmos-router.com.

Если вы получали наше более раннее уведомление о миграции, в нём был указан direct.zetaapi.ai: этот домен остаётся действительным и эквивалентен.

Проверка доступности домена

Любой запрос к этому домену вне двух указанных выше эндпоинтов — включая корневой путь / — обрывается без ответа. curl покажет Empty reply from server или HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR, а не 404. Это намеренная политика безопасности, и она не означает, что домен недоступен.

Чтобы убедиться, что домен работает, отправьте POST на сам эндпоинт (ключ не нужен, квота не расходуется):

curl -i -X POST https://image.zetaapi.ai/v1/images/generations \
  -H "Content-Type: application/json" -d '{}'

Ответ 401 Authorization Required означает, что DNS, TLS и шлюз работают корректно — сервис просто просит ваш API-ключ.

Эндпоинты

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

Параметры

curl

curl https://image.zetaapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red panda coding at night, neon rim light, 16:9 cinematic banner",
    "n": 1
  }'

Python (openai SDK)

import base64
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://image.zetaapi.ai/v1")

resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red panda coding at night, neon rim light, 16:9 cinematic banner",
    n=1,
)

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

Node.js (openai SDK)

import { writeFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxxx",
  baseURL: "https://image.zetaapi.ai/v1",
});

const resp = await client.images.generate({
  model: "gpt-image-2",
  prompt: "a red panda coding at night, neon rim light, 16:9 cinematic banner",
  n: 1,
});

writeFileSync("out.png", Buffer.from(resp.data[0].b64_json, "base64"));

Ответ

{
  "created": 1730000000,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "usage": { "input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036 }
}

По умолчанию возвращается b64_json (PNG в base64). Передайте "response_format": "url", чтобы получить ссылку на изображение.

Размеры вывода

Задавайте соотношение сторон в промпте, а не параметром size.

gpt-image-2 всегда рендерит с фиксированным бюджетом около 1,57 мегапикселя. Поднять его нельзя — просьба про «4K» или «3840x2160» в промпте не даёт больше пикселей. Зато вы можете управлять формой: описанное в промпте соотношение сторон соблюдается точно.

Поддерживаемый диапазон — от 1:3 до 3:1. Обычные соотношения попадают точно (16:9 → 1672 × 941); у границ выдаётся ближайший доступный размер — запрос 1:3 по факту даёт ~1:2,9. Стоимость одинакова для любого соотношения, так как число пикселей постоянно.

Параметр size принимается, чтобы SDK OpenAI продолжали работать, но игнорируется — size: "1024x1536" с нейтральным промптом всё равно вернёт квадрат. Если нужен точный размер в пикселях, генерируйте в ближайшем соотношении и меняйте размер локально.

Нужно действительно более высокое разрешение? Ограничение по пикселям задано вышестоящим провайдером gpt-image-2 и не меняется на нашей стороне — используйте Gemini 3 Pro Image, который выдаёт до 17 МП.

Высокое разрешение: Gemini 3 Pro Image

Для задач, где нужны реальные пиксели — печать, большие баннеры, обои — используйте gemini-3-pro-image-preview. Разрешение выбирается и соблюдается точно. Размеры ниже измерены без aspect_ratio — если задать его, ширина и высота изменятся при том же уровне пикселей:

Эта модель недоступна на /v1/images/* — вышестоящий провайдер отдаёт её только через chat completions. Два отличия от Images API:

1. Вызывайте POST /v1/chat/completions и передавайте разрешение в extra_body.
2. Изображение возвращается как Markdown data-URI внутри choices[0].message.content, а не как data[0].b64_json.

curl https://api.staging.cosmos-router.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "messages": [{"role": "user", "content": "Generate an image: a red panda coding at night, neon rim light"}],
    "extra_body": {"google": {"image_config": {"image_size": "4K"}}}
  }'

import base64, re
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://api.staging.cosmos-router.com/v1")

resp = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=[{"role": "user", "content": "Generate an image: a red panda coding at night"}],
    # SDK разворачивает extra_body на верхний уровень тела запроса, а шлюз
    # читает поле `extra_body` верхнего уровня — поэтому нужен ещё один
    # уровень вложенности. Без него запрос молча падает до 1K.
    extra_body={"extra_body": {"google": {"image_config": {"image_size": "4K"}}}},
)

# content: "Image generated successfully.\n![image](data:image/png;base64,iVBOR...)"
content = resp.choices[0].message.content
m = re.search(r"base64,([A-Za-z0-9+/=]+)", content or "")
if not m:
    raise RuntimeError(f"no image in response (refused or plain text): {content!r}")
with open("out.png", "wb") as f:
    f.write(base64.b64decode(m.group(1)))

Примечания:

• Тарификация по токенам, как в чате: 2K — примерно 1 120 image-токенов (≈ $0,06), 4K — около 2 000 (≈ $0,09). Тарифы — на странице цен.
• В том же блоке image_config поддерживается aspect_ratio (например, "16:9").
• Без стриминга и медленнее, чем gpt-image-2 на низких разрешениях: обычно 20–60 с, иногда дольше на 4K. Важно: запрос идёт по чат-маршруту, где бюджет шлюза на первый байт — 90 с; 4K со сложным промптом может вернуть 504. Повторите запрос или снизьте до 2K.
• PNG в 4K весит ~19 МБ до base64, то есть JSON-ответ — около 25 МБ. Убедитесь, что клиент и прокси перед ним принимают такой размер.

Вывод 4K в консоли

Без кода: откройте консоль → Playground генерации изображений и выберите Разрешение → «4K (длинная сторона >= 3840)». Работает на обеих вкладках — генерации и редактирования.

• Результат сразу возвращается в 4K — сохраните его кнопкой «Скачать» в правом верхнем углу
• В этом режиме за один запуск создаётся одно изображение
• Нужен достаточно свежий десктопный Chrome или Edge; в неподдерживаемых браузерах пункт неактивен

Это возможность консоли. При вызове gpt-image-2 через API вывод по-прежнему составляет около 1,57 МП, как описано выше.

Редактирование изображений (edits)

Редактирование использует multipart/form-data: загрузите исходное изображение (обязательно) и необязательную маску (прозрачные области перерисовываются):

curl https://image.zetaapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxxxx" \
  -F model=gpt-image-2 \
  -F 'prompt=сделать центральный квадрат синим' \
  -F image=@source.png \
  -F mask=@mask.png

• Исходное изображение + маска суммарно ≤ 14 МБ (больше — 413)
• Форматы: png / jpeg
• size работает так же, как в generations — принимается и игнорируется; см. Размеры вывода

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

В Codex есть встроенный инструмент image_gen, но на этой платформе он не работает — это не вопрос настройки, искать переключатель бесполезно.

image_gen — это hosted-инструмент, жёстко привязанный в Codex к входу через ChatGPT. В любой сессии с API-ключом и собственным base_url (именно так настраивают cc-switch и похожие инструменты) он вообще не попадает в список инструментов модели, а [features] image_generation = true на такую сессию не влияет. OpenAI ведёт issue #24465; обходного пути сейчас нет.

Мы выпустили плагин для Codex, который закрывает этот пробел:

codex plugin marketplace add Hermerz/zetaapi-codex-plugins
codex plugin add zeta-imagegen@zetaapi
export ZETAAPI_KEY=sk-ваш-ключ

После установки достаточно попросить Codex обычными словами — «нарисуй киберпанк-город ночью, 16:9». Редактирование тоже работает («сделай эту картинку зимней» плюс путь к локальному файлу).

Плагин принимает только ZETAAPI_KEY либо переиспользует ключ активного model_provider, если его base_url указывает на эту платформу. Он никогда не читает учётные данные других провайдеров — ключ шлюза по виду неотличим от ключа OpenAI или Anthropic, и угадывание отправило бы ваши настоящие сторонние ключи не туда. Поэтому принадлежность определяется по base_url, а не по самому ключу. Исходники открыты: Hermerz/zetaapi-codex-plugins

Не хотите ставить плагин? Codex умеет выполнять команды: оберните curl выше в скрипт и попросите Codex его вызвать — результат тот же.

Оплата, задержка и таймаут

• Оплата за изображение: каждая генерация / редактирование списывает реальную квоту с ключа; коэффициенты — на странице цен. Редактирование подаёт всё исходное изображение на вход, поэтому входных токенов заметно больше.
• Задержка: генерация обычно занимает 20–60 с, но при сложных промптах (мультивид, сверхдетальный рендер) или пиковой нагрузке может превысить 3 минуты. Установите таймаут клиента ≥ 300 с: шлюз возвращает 504 только после 240 с без первого байта от апстрима, поэтому более раннее отключение — просто потерянное ожидание. Для редактирования (/v1/images/edits) нужно больше: таймаут клиента обычно отсчитывается с начала загрузки, тогда как 240-секундный бюджет шлюза стартует только после её завершения — ставьте ≥ время загрузки + 300 с (для надёжности ≥ 400 с).
• Ответы с изображениями не потоковые — полный результат приходит сразу.

Коды ошибок

Совпадают с остальными эндпоинтами. Частые:

Полный список в API Reference.

Дополнительно

• Попробовать вживую → Playground изображений в консоли
• Общий API → API Reference
• Оплата → страница цен