API reference

Полная схема публичного REST API. Доступен на тарифах Pro и Max. Получите ключ на /account/api.

Предпочитаете Postman? Скачайте нашу коллекцию v2.1 — вставьте ваш ключ gimg_… в переменную apiKey.

Авторизация

Все эндпоинты принимают токен Bearer в заголовке Authorization. Токены всегда начинаются с gimg_.

Authorization: Bearer gimg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Лимиты запросов

600 запросов / час / ключ, не более 5 одновременно. В каждом ответе содержатся:

X-RateLimit-Limit — фиксировано на 600
X-RateLimit-Remaining — оставшиеся вызовы в текущем окне
X-RateLimit-Reset — epoch-секунды, когда окно сбросится
Retry-After — секунды до следующего разрешённого вызова (только при 429)

Идемпотентность

Передавайте Idempotency-Key в POST-запросах. Повторная отправка того же ключа возвращает существующую запись генерации, а не списывает кредиты дважды.

POST/api/v1/generate

Отправить генерацию text-to-image ИЛИ image-edit. Возвращается сразу с generationId; опрашивайте /api/v1/generations/:id для получения результата.

Body

promptstring ≤ 4000 charsобязательно
Описание на естественном языке. Помогает терминология фотографов (камера, объектив, освещение).
type"text2img" | "edit"
По умолчанию 'text2img'. Для 'edit' требуется inputImageKeys.
size"1024x1024" | "1024x1536" | "1536x1024"
Соотношение сторон. По умолчанию 1024x1024.
quality"low" | "medium" | "high"
По умолчанию medium. high = HD 2K. low — это Fast (1cr).
n1–4
Количество вариантов. По умолчанию 1.
inputImageKeysstring[] (max 4)
R2-ключи, возвращённые /api/v1/upload. Обязательны при type=edit.

Responses

202 Acceptedjson
{ "generationId": "...", "status": "queued" }
400 Bad Requestjson
Некорректный body. Ошибка содержит сообщение валидации Zod.
401 Unauthorizedjson
Отсутствует или некорректен Bearer-ключ.
402 Payment Requiredjson
Недостаточно кредитов или достигнут месячный лимит вычислений.
403 Forbiddenjson
Требуется тариф Pro или Max.
422 Unprocessablejson
Промпт заблокирован политикой контента.
429 Too Many Requestsjson
Достигнут лимит запросов. См. Retry-After.

POST/api/v1/upload

Получить presigned R2 PUT URL для загрузки входного изображения. Двухшаговый процесс: этот эндпоинт возвращает URL, вы напрямую делаете PUT с байтами.

Body

filenamestring ≤ 200обязательно
Отображаемое имя; не используется для хранения.
contentType"image/png" | "image/jpeg" | "image/webp"обязательно
Должен быть строго одним из этих трёх значений.
sizenumber (bytes ≤ 10 MB)обязательно
Размер файла, который вы планируете загрузить через PUT. Используется для валидации.

Response (200)

urlstring
Presigned PUT URL, действует 5 минут.
keystring
R2-ключ — передавайте его в inputImageKeys при вызове /api/v1/generate.

GET/api/v1/generations/:id

Опросить статус генерации. Возвращается сразу с текущим состоянием.

Response (200)

idstring
ID генерации.
status"queued" | "running" | "succeeded" | "failed" | "blocked"
'blocked' = модерация контента отклонила вход или выход (кредиты возвращены).
typestring
text2img | edit | upscale | …
outputsArray<{ png, webp, width, height }>
Заполняется при status=succeeded. URL-адреса публичные, неизменяемые, кэшируются в CDN.
errorstring | null
Заполняется при status=failed или status=blocked.
costCreditsnumber
Списанные кредиты (возвращаются при blocked или failed).
createdAt / completedAtISO 8601
Временные метки.

Исходящие webhooks

Откажитесь от опроса: зарегистрируйте HTTPS-эндпоинты, чтобы получать события generation.succeeded и generation.failed по мере их возникновения. Управление через /api/account/webhooks.

Регистрация

curl -X POST https://gptimage2.plus/api/account/webhooks \
  -H "Cookie: <your session cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/gptimg",
    "events": ["generation.succeeded", "generation.failed"],
    "label": "Production app"
  }'
# → { "id": "...", "secret": "whsec_..." }   ← copy this, shown ONCE

Полезная нагрузка события

POST https://your-app.com/hooks/gptimg
X-Gptimg-Event: generation.succeeded
X-Gptimg-Signature: <hex sha256 hmac of body>
X-Gptimg-Delivery: <uuid for dedup>
Content-Type: application/json

{
  "event": "generation.succeeded",
  "data": {
    "generationId": "...",
    "type": "text2img",
    "status": "succeeded",
    "outputs": [{ "png": "...", "webp": "...", "width": 1024, "height": 1024 }],
    "createdAt": "2026-04-26T01:23:45.000Z",
    "completedAt": "2026-04-26T01:23:50.000Z"
  }
}

Проверка подписи

// Node example
import crypto from "crypto";
const expected = crypto
  .createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");
const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-gptimg-signature"])
);

Таймаут: 5 секунд на попытку. Мы повторяем запросы при non-2xx ответах до 3 раз с экспоненциальной задержкой (30s → 2m → 10m). После 8 последовательных неудач webhook автоматически отключается — повторно включите его в /account/webhooks.