Справочник API
Все эндпоинты API СОЮЗ на одной странице — аутентификация, модели, чат, картинки, видео, джобы, файлы, вебхуки. Параметры, форматы ответов, коды ошибок.
Базовый URL: https://api.souz.ai/v1
Аутентификация — Bearer-ключ в каждом запросе (кроме файлов по подписанной ссылке):
Authorization: Bearer sk-souz-...
Все запросы и ответы — JSON (Content-Type: application/json). Ошибки — единый формат { "error": { "code", "message", "type" } }, подробности: Ошибки.
GET /v1/credits
Остаток кредитов и лимит ключа — для мониторинга («алерт до того, как кончились»).
curl https://api.souz.ai/v1/credits -H "Authorization: Bearer sk-souz-..."
| Поле | Описание |
|---|---|
balance |
Доступно к трате (кредиты) |
reserved |
Удержано выполняющимися джобами |
credit_value_usd |
Курс: 0.01 (1 кредит = 1¢) |
rate_limit.requests_per_minute |
Действующий лимит этого ключа |
GET /v1/models
Каталог моделей с возможностями, лимитами и тарифами.
curl https://api.souz.ai/v1/models -H "Authorization: Bearer sk-souz-..."
Ответ: { "object": "list", "data": [ ... ] }, элемент:
| Поле | Описание |
|---|---|
id |
ID модели (souz/...) — его передаёшь в model |
name |
Человеческое название |
modality |
chat / image / video |
capabilities.aspect_ratios |
Допустимые соотношения сторон |
capabilities.resolutions |
Разрешения (картинки): 1K/2K/4K |
capabilities.durations |
Длительности (видео), сек |
capabilities.max_references |
Макс. референсов |
capabilities.requires_reference |
true — референс обязателен (например, оживление картинки) |
capabilities.advanced_params |
Белый список продвинутых полей |
pricing |
Правило цены (см. Кредиты) |
limits |
max_prompt_chars, max_image_mb, image_formats |
POST /v1/chat/completions
Синхронный чат, OpenAI-совместимый (текст, vision, tools, reasoning, стриминг). Полное описание: Чат.
Тело: стандартное OpenAI (model, messages, stream, temperature, max_tokens, tools, response_format, reasoning_effort, …). Лимит — 25 МБ.
Ответ: стандартный OpenAI chat.completion (или SSE-поток при stream: true). Дополнительно usage.cost — списанные кредиты.
Ошибки: 401, 402 insufficient_credits, 404 model_not_found, 413, 429, 502 model_unavailable.
POST /v1/images/generations
Создать джобу генерации картинки. Полное описание: Картинки.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
model |
string | ✅ | ID модели |
prompt |
string | ✅ | Описание |
aspect_ratio |
string | — | 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 auto (по умолчанию 1:1) |
resolution |
string | — | 1K / 2K / 4K (по умолчанию 1K) |
size |
string | — | OpenAI-стиль: 1024x1024 / 1792x1024 / 1024x1792 / 2048x2048 |
image / images |
string / string[] | — | Референсы: data URL или https URL |
callback_url |
string | — | Вебхук этой джобы |
| прочие поля | — | — | Продвинутые параметры модели (белый список) |
Заголовки: Idempotency-Key — защита от дублей при ретраях.
Ответ 202 (или 200, если джоба уже разрешилась — например, идемпотентный повтор): объект джобы — см. ниже. При callback_url добавляется webhook_secret (показывается один раз).
POST /v1/videos/generations
Создать джобу генерации видео. Полное описание: Видео.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
model |
string | ✅ | ID модели |
prompt |
string | ✅ | Описание (до 5000 символов) |
aspect_ratio |
string | — | 16:9 / 9:16 / 1:1 / auto (по умолчанию 16:9) |
duration |
string|number | — | Секунды (по умолчанию 5; допустимые — у модели) |
image / images |
string / string[] | — | Референсы (data URL или https URL) |
callback_url |
string | — | Вебхук этой джобы |
| прочие поля | — | — | Продвинутые параметры модели: mode, sound, negative_prompt, … |
Ответ: как у картинок (object: "video").
GET /v1/jobs/{id}
Статус и результат джобы. Полное описание: Джобы.
Объект джобы:
| Поле | Описание |
|---|---|
id |
ID джобы |
object |
image / video / chat |
model |
Модель |
status |
queued → in_progress → completed / failed |
price |
Цена в кредитах |
created_at |
Unix-время создания |
data |
При completed: [{ "url": "подписанная ссылка" }] |
error |
При failed: { code, message, type } |
GET /v1/files/{name}?exp=...&sig=...
Скачать сгенерированный файл. Аутентификация — подпись в URL (ссылку выдаёт джоба), Bearer не нужен. Ссылку можно открывать в браузере.
Ошибки: 403 forbidden (подпись истекла — перезапроси джобу), 410 file_expired (файл удалён по сроку ~24 ч), 502 storage_unavailable.
POST /v1/webhooks
Зарегистрировать постоянный вебхук. Тело: { "url": "https://..." }. Ответ 201: { id, object: "webhook", url, secret } — secret показывается один раз. Полное описание: Вебхуки.
GET /v1/webhooks
Список вебхуков: { "object": "list", "data": [{ id, url, enabled, created_at }] }.
DELETE /v1/webhooks/{id}
Отключить вебхук. Ответ: { id, object: "webhook", deleted: true }.
GET /health
Проверка живости API (без аутентификации): { "ok": true }.
Частота запросов
60 запросов/мин на ключ; 429 + Retry-After при превышении. Подробности: Лимиты.