# Принципы

## Снаружи — всегда OpenAI-формат

Публичный API СОЮЗ всегда в формате OpenAI — де-факто стандарте индустрии. Клиент подключается, меняя **две строки**: `base_url` и `api_key`. Код, написанный под OpenAI SDK, работает как есть.

Провайдерские форматы (Google Native, внутренние API видео-провайдеров) — наша внутренняя кухня: мы переводим твой запрос в формат нужного провайдера сами. Ты их никогда не видишь.

Там, где у OpenAI нет устоявшегося стандарта (видео), мы добавляем тонкий слой в той же манере: тот же Bearer-ключ, тот же стиль JSON и ошибок.

## Просто по умолчанию — полная мощь по желанию

Базовый запрос максимально простой: `model` + `prompt`, и всё работает с разумными настройками.

Но если нужен полный функционал модели — любые продвинутые параметры (`negative_prompt`, `cfg_scale`, `sound`, `mode`, …) кладутся **прямо верхним уровнем** в тот же JSON. Они проверяются по белому списку конкретной модели: неизвестное поле → понятная ошибка `invalid_input`, без списания кредитов. Какие поля у какой модели — в [каталоге моделей](/models) и в `GET /v1/models`.

Простой путь никогда не усложняется из-за продвинутого.

## Надёжность: водопад провайдеров

У каждой модели может быть несколько провайдеров. Если первый недоступен или вернул сбой — запрос автоматически уходит к следующему. Ты этого не замечаешь: модель, цена и формат ответа не меняются.

Цена для тебя **фиксирована за модель** — переключение провайдеров меняет нашу маржу, а не твой счёт.

## Деньги: честно и прозрачно

- **1 кредит = 1 цент США ($0.01).** Все цены — в кредитах.
- Цена видна заранее ([каталог](/models)) и по факту: поле `price` у джобы, `usage.cost` в ответе чата.
- Списание — только за успешный результат. Сбой генерации → автоматический возврат резерва.
- Баланс и история — на [dash.souz.ai](https://dash.souz.ai).

## Асинхронность для тяжёлых задач

Картинки и видео создаются асинхронно: сразу получаешь `job_id`, результат — опросом `GET /v1/jobs/{id}` или [вебхуком](/webhooks). Это единственная схема, которая честно масштабируется и не рвёт соединения на минутных генерациях. Чат — синхронный (и со стримингом).

## Результаты — по ссылке, хранение ~24 часа

Готовые файлы отдаются подписанной ссылкой. Хранение — около суток, дальше файл удаляется (политика zero-retention: мы не храним твой контент дольше необходимого). Скачивай результат сразу после готовности.