Документация API

REST‑API для генерации изображений, видео и озвучки. Один общий контракт, асинхронная генерация, оплата по факту с API‑кошелька. Все суммы — в рублях.

API media‑only: доступны только медиа‑модели (изображения, видео, аудио). Полный список — в каталоге. Текстовые/LLM‑модели через этот API не вызываются.

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

Три шага: создай ключ в консоли разработчика, отправь генерацию, опроси результат.

# 1. Отправляем генерацию изображения
curl -X POST https://api.gptrf.ru/api/public/v1/images/generate \
  -H "Authorization: Bearer gptrf_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"неоновый город под дождём"}'

# 202 Accepted
{
  "id": "4f9c8b2e-1a7d-4e3b-9c10-2f5a6b7c8d90",
  "status": "queued",
  "task_id": "task_abc123",
  "cost_rub": 8.00
}

# 2. Опрашиваем статус по id
curl https://api.gptrf.ru/api/public/v1/creations/4f9c8b2e-1a7d-4e3b-9c10-2f5a6b7c8d90 \
  -H "Authorization: Bearer gptrf_live_xxxxxxxxxxxxxxxx"

# 200 OK — когда готово
{
  "id": "4f9c8b2e-1a7d-4e3b-9c10-2f5a6b7c8d90",
  "status": "completed",
  "result_urls": ["https://cdn.gptrf.ru/o/4f9c8b2e.png"]
}

Аутентификация

Передавай API‑ключ в заголовке Authorization: Bearer gptrf_live_… (или X-API-Key: gptrf_live_…). Ключ создаётся в консоли и показывается один раз — сохрани его сразу. Ключи бывают двух окружений: gptrf_live_… и gptrf_test_….

# Любой из двух заголовков:
Authorization: Bearer gptrf_live_xxxxxxxxxxxxxxxx
X-API-Key: gptrf_live_xxxxxxxxxxxxxxxx

Запросы с ключа списываются с отдельного API‑кошелька (метрическая оплата по факту); тарифы и подписки сайта на этот канал не действуют. Без валидного ключа — 401 ERR_API_KEY_INVALID.

Каталог моделей

Возвращает список доступных медиа‑моделей с категорией, названием и справочной ценой. Необязательный фильтр ?category= принимает image, video или audio (иное значение — 400).

curl "https://api.gptrf.ru/api/public/v1/models?category=image" \
  -H "Authorization: Bearer gptrf_live_…"

# 200 OK
{
  "models": [
    { "id": "nano-banana",      "category": "image", "display_name": "Nano Banana",     "price_rub": "8.00",  "unit": "per_image" },
    { "id": "veo-3-1-text-to-video",      "category": "video", "display_name": "Veo 3.1",  "price_rub": "60.00", "unit": "per_8_sec" },
    { "id": "seedance-2-text-to-video",   "category": "video", "display_name": "Seedance 2", "price_rub": "20.00", "unit": "per_second" },
    { "id": "x-ai/grok-video",            "category": "video", "display_name": "Grok Video", "price_rub": "30.00", "unit": "per_generation" },
    { "id": "eleven_multilingual_v2",     "category": "audio", "display_name": "Eleven Multilingual v2", "price_rub": "12.00", "unit": "per_1000_chars" }
  ]
}

Async и статусы

Любая генерация асинхронная. POST возвращает 202 Accepted с id; результат узнают опросом GET /creations/{id} или через вебхук.

Тело ответа на любую генерацию (202):

{
  "id": "4f9c8b2e-…",     // id создания — для опроса статуса
  "status": "queued",      // queued | processing | completed | failed
  "task_id": "task_abc123",// id задачи у провайдера (может быть null вначале)
  "cost_rub": 8.00         // списано с API-кошелька (₽)
}

Возможные значения статуса:

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

Передавай X-Idempotency-Key на любой POST‑генерации — повтор с тем же ключом вернёт тот же результат и не спишет дважды. Используй уникальный ключ (UUID) на каждую логическую операцию — безопасно для ретраев при сетевых сбоях.

curl -X POST https://api.gptrf.ru/api/public/v1/images/generate \
  -H "Authorization: Bearer gptrf_live_…" \
  -H "X-Idempotency-Key: 7f3a1c2e-9b8d-4a5f-6c7e-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{"model":"nano-banana","prompt":"кот в скафандре"}'

Ошибки

Все ошибки — единый JSON‑конверт со стабильными кодами:

{
  "error": {
    "code": "ERR_INSUFFICIENT_BALANCE",
    "message": "insufficient api wallet balance",
    "details": { "required_rub": 8.00, "top_up_url": "/dashboard/developer/wallet" }
  }
}

Лимиты

Лимиты задаются на каждый API‑ключ:

Лимиты ключа настраиваются в консоли. При 429 повтори запрос после указанного интервала.

Оплата

Канал Developer API оплачивается с отдельного API‑кошелька по факту использования (pay‑as‑you‑go), независимо от тарифов и подписок сайта. За каждый успешный вызов списывается cost_rub (он возвращается в ответе). При сбое генерации сумма возвращается автоматически.

Пополнить кошелёк и смотреть расходы — в консоли → Кошелёк. При нулевом балансе генерация вернёт 402 ERR_INSUFFICIENT_BALANCE ещё до  запуска (списания не происходит).

images.generate

Генерирует изображение по промпту. Если передать входное изображение (image_file_id) — модель выполнит редактирование (это та же операция, не отдельная). Тарификация — за изображение.

Параметры тела

Пример

curl -X POST https://api.gptrf.ru/api/public/v1/images/generate \
  -H "Authorization: Bearer gptrf_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "prompt": "горное озеро на рассвете, фотореализм",
    "aspect_ratio": "16:9",
    "n": 1
  }'

# 202 Accepted
{ "id": "4f9c…", "status": "queued", "task_id": "task_…", "cost_rub": 30.00 }

images.upscale

Увеличивает разрешение изображения (Topaz / Recraft). Промпт не нужен.

curl -X POST https://api.gptrf.ru/api/public/v1/images/upscale \
  -H "Authorization: Bearer gptrf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"topaz-image-upscale","image_file_id":"file_abc123","upscale_factor":4}'

images.remove-background

Удаляет фон с изображения (Recraft). Промпт не нужен.

curl -X POST https://api.gptrf.ru/api/public/v1/images/remove-background \
  -H "Authorization: Bearer gptrf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"recraft-remove-background","image_file_id":"file_abc123"}'

video.generate

Генерирует видеоклип из текста или из изображения (image‑to‑video, если передать image_file_id).

Тарификация зависит от модели и считается тремя способами:

• за блок фиксированной длины: veo — за каждые 8 сек, kling — за 5 сек, sora — за 10 сек (короткий клип = 1 блок, длиннее — кратно: цена × ceil(длительность / блок));
• за секунду: seedance (цена × длительность);
• фиксированно за всю генерацию: grok / sora‑pro (единица video).

Точная сумма приходит в cost_rub; единица тарификации каждой модели — в поле unit каталога /models.

curl -X POST https://api.gptrf.ru/api/public/v1/video/generate \
  -H "Authorization: Bearer gptrf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"veo-3-1-text-to-video","prompt":"кот идёт по полю на закате","duration":8}'

audio.generate (TTS)

Синтез речи (ElevenLabs). Возвращает аудиофайл. Оплата — за каждые 1000 символов текста.

curl -X POST https://api.gptrf.ru/api/public/v1/audio/generate \
  -H "Authorization: Bearer gptrf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"model":"eleven_multilingual_v2","text":"Привет! Это синтез речи.","voice":"Rachel"}'

audio.dialogue

Многоголосый диалог (ElevenLabs text‑to‑dialogue‑v3): 2–20 реплик, у каждой свой голос. Оплата — за каждые 1000 символов суммарно по всем репликам.

curl -X POST https://api.gptrf.ru/api/public/v1/audio/dialogue \
  -H "Authorization: Bearer gptrf_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogue": [
      { "text": "Привет, как дела?",     "voice": "Sarah" },
      { "text": "Отлично, спасибо!",     "voice": "Roger" }
    ]
  }'

uploads

Загружает входной файл (изображение, аудио или видео) и возвращает file_id для использования в полях image_file_id / audio_file_id / video_file_id. Формат — multipart/form-data.

curl -X POST https://api.gptrf.ru/api/public/v1/uploads \
  -H "Authorization: Bearer gptrf_live_…" \
  -F "file=@/path/to/image.jpg" \
  -F "kind=image"

# 200 OK
{
  "file_id": "file_abc123",
  "url": "https://storage.gptrf.ru/…",
  "expires_at": "2026-07-16T12:00:00Z"
}

creations

Возвращает статус создания по id из ответа генерации. Опрашивай не чаще раза в 5 секунд на одно создание.

# выполняется
{ "id": "4f9c…", "status": "processing" }

# готово (медиа)
{ "id": "4f9c…", "status": "completed", "result_urls": ["https://cdn.gptrf.ru/o/4f9c.png"] }

# ошибка (средства возвращены)
{ "id": "4f9c…", "status": "failed", "error": "генерация не удалась" }

Доступ привязан к аккаунту: ты видишь только свои создания — чужой или несуществующий id вернёт 404.

Вебхуки

Чтобы не опрашивать статус, зарегистрируй URL вебхука в консоли → Вебхуки. На готовности (или сбое) создания мы пришлём POST на твой URL с подписью.

Доставка с ретраями и экспоненциальной задержкой — отвечай 2xx как можно быстрее и обрабатывай событие асинхронно.

CLI, MCP и Skills

Кроме ключей, к тем же операциям можно подключиться из терминала и AI‑редакторов через вход по аккаунту (OAuth) — тогда генерации списываются с баланса аккаунта, а не с API‑кошелька:

• CLI @gptrf/cli — команды gptrf image, gptrf video, gptrf audio, gptrf model.
• MCP — сервер инструментов для Claude Code, Cursor и других MCP‑клиентов.
• Skills — плагин для Claude Code.

Как подключить — на странице обзора для разработчиков.