# Справочник API

Базовый URL: `https://api.souz.ai/v1`

Аутентификация — Bearer-ключ в каждом запросе (кроме файлов по подписанной ссылке):

```text
Authorization: Bearer sk-souz-...
```

Все запросы и ответы — JSON (`Content-Type: application/json`). Ошибки — единый формат `{ "error": { "code", "message", "type" } }`, подробности: [Ошибки](/errors).

---

## GET /v1/credits

Остаток кредитов и лимит ключа — для мониторинга («алерт до того, как кончились»).

```bash
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

Каталог моделей с возможностями, лимитами и тарифами.

```bash
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` | Правило цены (см. [Кредиты](/credits)) |
| `limits` | `max_prompt_chars`, `max_image_mb`, `image_formats` |

---

## POST /v1/chat/completions

Синхронный чат, OpenAI-совместимый (текст, vision, tools, reasoning, стриминг). Полное описание: [Чат](/chat).

**Тело:** стандартное 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

Создать джобу генерации картинки. Полное описание: [Картинки](/images).

| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `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

Создать джобу генерации видео. Полное описание: [Видео](/videos).

| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `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}

Статус и результат джобы. Полное описание: [Джобы](/jobs).

**Объект джобы:**

| Поле | Описание |
|---|---|
| `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` показывается один раз. Полное описание: [Вебхуки](/webhooks).

## 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` при превышении. Подробности: [Лимиты](/limits).