Предварительный выбор каналов

POSThttps://api.souz.ai/v1/models/{id}/routing/preview

Проверяет параметры и настройки выбора без создания платного запроса. Настройки роутинга аккаунта и закреплённые диалоги не используются: передайте нужные настройки явно. Отказ — тем же конвертом, что у запуска: capability_mismatch или invalid_request с detail[] (path, reason, allowed); путь параметра из params — как в запросе запуска.

Авторизация

BearerAuth

API-ключ из кабинета souz.ai — запускает модели. Ключ управления здесь не подходит: 403 forbidden с detail[].reason: requires_api_key.

ManagementKey

Ключ управления из кабинета souz.ai (выдают владелец и администратор аккаунта — себе или участнику). Даёт ровно то, что его держатель видит и может в кабинете: баланс, историю операций и запросов, расходы, обычные ключи, настройки аккаунта — с той же ролью, лимитами и цифрами. Модели не запускает. Обычный API-ключ здесь не подходит: 403 forbidden с detail[].reason: requires_management_key.

ClientSession

Сессия кабинета souz.ai в браузере — те же ручки, что у ключа управления.

Параметры пути

idstringобязательно

Id модели из каталога.

Пример: "nano-banana-pro"

Тело запроса обязательно

application/json

Схема RoutingPreviewRequest

Других полей нет.

audio_inputboolean

Чат — в messages будет звук.

billed_secondsinteger

Минимум: 1

Максимум: 86400

file_inputboolean

Чат — в messages будет файл (PDF).

input_tokensinteger

Минимум: 0

Максимум: 16777216

max_price_multiplierMaxPriceMultiplier | null

ninteger

Чат — сколько вариантов ответа; пределы выхода каналов и оценка считаются на все.

Минимум: 1

Максимум: 128

output_tokensinteger

Минимум: 1

Максимум: 16777216

paramsQuoteGenerationParams

routingRouting

routing_optionsRoutingOptions

speech_charactersinteger

Минимум: 1

Максимум: 1000000

speech_dialogueboolean

Речь — запрос с dialogue вместо input.

speech_instructionsboolean

Речь — запрос с полем instructions.

speech_output_secondsinteger

Минимум: 1

Максимум: 86400

speech_utf16_charactersinteger

Минимум: 1

Максимум: 2000000

streamboolean

structured_outputboolean

toolsboolean

video_inputboolean

Чат — в messages будет видео.

visionboolean

Ответы

200Предварительный план.

application/json

Схема RoutingPreview

channelsarray[RoutingPreviewChannel]обязательно

Каналы плана в порядке попыток: первый — тот, с которого начнётся запрос, следующие — запасные. Пустой список — запрос с этими условиями сейчас выполнить нельзя; почему — в excluded.

currencyCurrencyобязательно

estimated_priceinteger | null · int64обязательно

Оценка суммы первого канала цепочки для этих параметров. Может уточняться по сопоставимым выполненным запросам; итог зависит от фактического объёма и ставок на момент приёма. Запасной канал может стоить дороже. null — план пуст. План ознакомительный: при создании запроса он рассчитывается заново.

excludedarray[RoutingPreviewExclusion]обязательно

Каналы модели, которые в план не вошли, и почему. Каждый цвет — один раз.

generated_atstring · date-timeобязательно

modelstringобязательно

400Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

application/json

Error

401Нет ключа или ключ недействителен.

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. detail[].reason говорит, что именно: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed — роли, которым можно), not_key_author (секрет ключа открывает только тот, кто его создал).

application/json

Error

404Нет такого объекта у этого аккаунта.

application/json

Error

413Тело или файл больше предела (`invalid_input`, `detail[].reason: too_large`) или — только у `POST /v1/files` — загрузки аккаунта заняли квоту (`storage_limit_exceeded`).

application/json

Error

415Тип тела не тот, что принимает метод: `Content-Type: application/json` (у загрузки файла и транскрибации — `multipart/form-data`). В `detail[]` — `{"path": "body", "reason": "unsupported_format"}` и принимаемые типы.

application/json

Error

429Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

application/json

Error

Бесплатно, со своим ключом

Запрос

curl -X POST 'https://api.souz.ai/v1/models/{id}/routing/preview' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{}'

import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/models/{id}/routing/preview",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    json={},
)
print(response.json())

const response = await fetch("https://api.souz.ai/v1/models/{id}/routing/preview", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(await response.json());

Ответ

{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}