Принципы

Снаружи — всегда 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, без списания кредитов. Какие поля у какой модели — в каталоге моделей и в GET /v1/models.

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

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

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

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

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

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

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

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

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

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