# REST API Строфи

> Программный доступ к генерации Строфи по HTTP: кому он открыт, из чего состоит, чем отличается от подключения агента по MCP и с чего начать интеграцию.

Источник: https://strophe.app/docs/product/developers/overview
Обновлено: 2026-08-26

REST API даёт вашей программе тот же каталог моделей и тот же счёт кредитов, что и редактор. Запрос уходит по HTTP, генерация встаёт в общую очередь, результат забирается ссылкой — холст при этом не участвует.

## Кому открыт

Доступ идёт вместе с командным планом, и распоряжается им владелец команды или её администратор: ключ работает от лица всей команды и тратит общий пул, поэтому выпускать его и подписываться на события вправе тот, кто за этот пул отвечает. Рядовому участнику остаётся подключение агента по MCP — оно открыто любой действующей подписке и тратит личный баланс. Как устроены команды и роли в них, описано в статье [Команда](https://strophe.app/docs/product/account/teams).

## Чем это отличается от подключения агента

Подключение по MCP рассчитано на чужого AI-агента: он читает описания моделей словами, сам выбирает подходящую и запускает генерацию по вашей просьбе в переписке. REST рассчитан на программу: тот же каталог отдаётся машинным JSON, выбор модели делаете вы, а ответ построен на кодах, а не на объяснениях.

Оба пути ведут к одному каталогу и к одному счёту. Генерации, запущенные через REST, видны в истории вместе с теми, что запустил агент.

## Из чего состоит

Базовый адрес — `https://strophe.app/api/v1`. Все запросы идут под ключом в заголовке `Authorization`, ответы всегда в JSON.

Ручек шесть групп:

- каталог моделей — `GET /families` и `GET /families/{id}`;
- генерации — запуск, состояние, история, отмена, предварительная оценка стоимости;
- файлы — `POST /files` превращает ваш файл в идентификатор входа;
- счёт — `GET /account` отвечает, сколько можно потратить прямо сейчас;
- вебхуки — уведомление о завершении генерации приходит на ваш адрес;
- машинное описание — `GET /openapi.json` отдаёт спеку OpenAPI, тоже под ключом.

## Порядок работы

Обычная последовательность выглядит так: выпустить ключ, посмотреть каталог, загрузить входные файлы, запустить генерацию, дождаться исхода и скачать результат.

1. [Ключ и права](https://strophe.app/docs/product/developers/authentication) — выпуск ключа, права, потолки траты.
2. [Запуск генерации](https://strophe.app/docs/product/developers/generation) — каталог, оценка, запуск, ожидание, результат.
3. [Вебхуки](https://strophe.app/docs/product/developers/webhooks) — исход приходит сам, без опроса.
4. [Ошибки и лимиты](https://strophe.app/docs/product/developers/errors-and-limits) — коды отказа, частота запросов, потолки размеров.

## Версия и совместимость

Версия стоит в пути: `/api/v1`. Внутри версии контракт не ломается — поля добавляются, но не исчезают и не меняют смысл, а набор кодов ошибок пополняется только новыми значениями. Ломающая правка означала бы `/api/v2`, и первая версия продолжила бы работать рядом.

Отсюда практическое правило для клиента: незнакомое поле в ответе игнорируется, незнакомый код ошибки обрабатывается как отказ своего класса — по числовому статусу HTTP и признаку `retryable`.