Алиасы параметров

Как передавать provider, reasoning_effort и allow_fallbacks прямо в строке model

Если ваш клиент не умеет отправлять дополнительные поля в body, часть routing- и reasoning-настроек можно передать прямо в строке model.

Alias-формат поддерживается только для chat-style API: /v1/chat/completions, /v1/responses и /v1/messages.

​

Что это даёт

С помощью alias-формата можно:

• выбрать конкретного провайдера через provider
• задать глубину reasoning через reasoning_effort
• включить или отключить fallback через allow_fallbacks

Если в model нет символа @, запрос обрабатывается как обычно.

​

Поддерживаемые эндпоинты

Эндпоинт	Поддержка
/v1/chat/completions	✅
/v1/responses	✅
/v1/messages	✅
Embeddings	❌
Audio	❌
Media	❌

​

Формат alias-строки

<model>@<key>=<value>&<key>=<value>

Примеры:

minimax/minimax-m2.5@reasoning_effort=high
minimax/minimax-m2.5@allow_fallbacks=false
anthropic/claude-opus-4-6@provider=Amazon Bedrock
minimax/minimax-m2.5@provider=DeepInfra&reasoning_effort=high&allow_fallbacks=false

В ответах API возвращается canonical model без alias-суффикса. Например, если вы отправили minimax/minimax-m2.5@reasoning_effort=high, в ответе придёт minimax/minimax-m2.5.

​

Поддерживаемые alias-параметры

Alias	Во что маппится	Что делает
provider	provider.only = [value]	Выбирает конкретный provider routing path
reasoning_effort	reasoning.effort = value	Управляет глубиной reasoning
allow_fallbacks	provider.allow_fallbacks = boolean	Разрешает или запрещает fallback на другие провайдеры

​

provider

provider работает так же, как обычное поле provider.only — передавайте тот же идентификатор, который у вас уже работает в provider.only.

anthropic/claude-opus-4-6@provider=Amazon Bedrock

​

reasoning_effort

Маппится в canonical-поле reasoning.effort. Поддерживаемые значения:

• max
• xhigh
• high
• medium
• low
• minimal
• none

Конкретная модель или провайдер могут поддерживать только часть значений. Например, Yandex AI Studio поддерживает только low, medium и high.

minimax/minimax-m2.5@reasoning_effort=high

​

allow_fallbacks

Допустимы только значения true и false.

minimax/minimax-m2.5@allow_fallbacks=false

​

Примеры запросов

Chat Completions

curl -X POST https://polza.ai/api/v2/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/minimax-m2.5@reasoning_effort=high",
    "messages": [
      { "role": "user", "content": "Ответь одним словом: да" }
    ]
  }'

​

Эквивалент в обычном body

Alias-формат — это сокращённая запись стандартных body-полей. Следующие запросы эквивалентны:

Через alias

{
  "model": "minimax/minimax-m2.5@reasoning_effort=high",
  "messages": [{ "role": "user", "content": "Привет" }]
}

Через alias

{
  "model": "minimax/minimax-m2.5@provider=DeepInfra&allow_fallbacks=false",
  "messages": [{ "role": "user", "content": "Привет" }]
}

​

Конфликты alias и body

Если одно и то же поведение задано и через alias, и через обычные поля body, API вернёт 400.

Конфликтами считаются:

• provider=... в model и любой объект provider в body
• reasoning_effort=... в model и reasoning.effort в body
• allow_fallbacks=... в model и provider.allow_fallbacks в body

Если вам нужна сложная routing-настройка (order, ignore, max_price и другие поля provider), используйте обычный body-контракт, а не alias-формат.

Пример конфликта, который вернёт 400:

{
  "model": "minimax/minimax-m2.5@reasoning_effort=high",
  "messages": [{ "role": "user", "content": "Привет" }],
  "reasoning": {
    "effort": "low"
  }
}

​

Ошибки валидации

API вернёт 400, если:

• используется неизвестный alias-ключ
• ключ повторяется несколько раз
• значение пустое
• строка alias имеет неправильный формат
• alias конфликтует с body

Невалидные примеры:

openai/gpt-4.1@
openai/gpt-4.1@provider
openai/gpt-4.1@provider=
openai/gpt-4.1@provider=google=foo
openai/gpt-4.1@provider=google&provider=openai
openai/gpt-4.1@foo=bar

​

Ограничения

• Поддерживаются только provider, reasoning_effort и allow_fallbacks
• Provider-specific параметры через alias не поддерживаются
• Percent-encoding и дополнительные escape-механизмы не поддерживаются
• Alias-формат не распространяется на embeddings, audio и media

​

Следующие шаги

Выбор провайдера

Полный список параметров routing через body-контракт

Reasoning

Подробнее о параметре reasoning и его значениях