Что умеет API
Каталог моделей
GET /api/v1/models — список моделей с назначением, полями, лимитами и стоимостью. Discovery вместо угадывания.
Один запрос на все модели
POST /api/v1/generations с телом { type, model, input }. Минимальный input работает для любой модели — остальное берётся из схемы.
Схема каждой модели
GET /api/v1/models/{id} возвращает поля как JSON-Schema: какие значения допустимы, что обязательно и сколько стоит вариант.
Ассеты и референсы
POST /api/v1/assets и /assets/import возвращают asset:// URI, который можно передать в schema-backed поля модели.
Понятные ошибки до списания
Поля проверяются по схеме модели до того, как потрачен хоть один токен; в ответе виден estimatedTokens — оценка стоимости до старта генерации.
IDEMPOTENCY_KEY="${IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.givon.ai/api/v1/generations \
-H "Authorization: Bearer $GIVON_API_KEY" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"image","model":"gpt-image-2.5-flare","input":{"prompt":"кот в очках читает книгу"}}'Discovery → вызов → результат
Внутренний реестр моделей — единственный источник правды. Он проецируется в три поверхности, которые не могут разойтись: REST API, каталог моделей в формате JSON-Schema и MCP. Поэтому поля, лимиты и стоимость в документации всегда совпадают с тем, что реально принимает генерация.
Сценарий простой: GET /models → выбираешь модель → копируешь пример input из её схемы → POST /generations → опрашиваешь статус по id вида gen_… → получаешь готовое медиа. Способ вызова учишь один раз, дальше он одинаков для всех моделей — меняются только модель и поля input.
С чего начать
Ключ
Выпусти API-ключ в кабинете: «Интеграции» → «Ключи». Секрет показывается один раз — сохрани сразу. Передавай ключ в заголовке Authorization: Bearer gvk_…
Модели
Через API доступны модели изображений, видео, музыки и озвучки. Полный список с полями и стоимостью — GET /api/v1/models или каталог в кабинете.
Стоимость
Запрос тратит токены твоего баланса. Безлимит Studio Pro не действует для API и MCP; скидки на указанные видеомодели сохраняются. Поле estimatedTokens в ответе показывает каталожную оценку, а не итоговую цену с учётом тарифа.
Асинхронность
Генерация обрабатывается в фоне: создаёшь запрос (POST /generations), получаешь id вида gen_…, опрашиваешь GET /generations/{id} до готовности.
Без дублей
Передай заголовок Idempotency-Key, чтобы повторная отправка того же запроса не создала вторую генерацию.
Подключение к AI-агенту
MCP (Model Context Protocol) — стандарт, по которому AI-агенты подключают внешние инструменты. Наш MCP-сервер даёт агенту тот же набор действий, что и REST: найти модель, прочитать её схему, запустить генерацию, проверить статус и узнать баланс.
Агент сам узнаёт, какие поля принимает модель, и формирует корректный запрос — параметры не нужно зашивать вручную. Это удобно, когда генерация Givon AI — один из шагов в более крупном агентном сценарии.
