Выбор моделей

ZvenoAI предоставляет единый API для работы с моделями разных вендоров (OpenAI, Anthropic, Google и др.) и выбором upstream-провайдера. Указывайте модель по slug и, при необходимости, настраивайте fallback и provider preferences.

Одна модель в запросе

Стандартный способ — передать строку с ID модели. ZvenoAI направит запрос к соответствующему провайдеру.

const response = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: 'Привет!' }],
})

Несколько моделей (параметр models)

Передайте массив ID моделей в параметре models, если хотите повысить надежность. ZvenoAI автоматически попробует модели по порядку, пока запрос не будет успешно обработан.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZVENOAI_API_KEY,
  baseURL: "https://api.zveno.ai/v1",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o",
  // ZvenoAI автоматически использует первую доступную модель из списка
  models: ["openai/gpt-4o", "anthropic/claude-3.5-sonnet"],
  messages: [{ role: "user", content: "Привет!" }],
});

from openai import OpenAI

client = OpenAI(
    api_key="ваш_ключ_zvenoai",
    base_url="https://api.zveno.ai/v1",
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Привет!"}],
    extra_body={
        "models": ["openai/gpt-4o", "anthropic/claude-3.5-sonnet"]
    }
)

// Для Go (github.com/sashabaranov/go-openai)
// Так как SDK строго типизирован, используйте структуру-обертку:
type ZvenoAIRequest struct {
    openai.ChatCompletionRequest
    Models []string `json:"models,omitempty"`
}

func main() {
    config := openai.DefaultConfig("ваш_ключ")
    config.BaseURL = "https://api.zveno.ai/v1"
    client := openai.NewClientWithConfig(config)

    req := ZvenoAIRequest{
        ChatCompletionRequest: openai.ChatCompletionRequest{
            Model: "openai/gpt-4o",
            Messages: []openai.ChatCompletionMessage{{Role: "user", Content: "Привет!"}},
        },
        Models: []string{"openai/gpt-4o", "anthropic/claude-3.5-sonnet"},
    }
    // Отправка через http.Client с маршалингом req в JSON
}

Параметры запроса

Поля model и models используются для выбора LLM модели:

model (string, обязательное) — ID модели для запроса. Используйте формат vendor/model: "openai/gpt-4o", "anthropic/claude-3.5-sonnet", "google/gemini-2.5-pro" и т.д.

models (array, опциональное) — Массив ID моделей для повышения надежности. Если модель из поля model недоступна, роутер автоматически попробует модели из этого списка по порядку. Пример: models: ["openai/gpt-4o", "anthropic/claude-3.5-sonnet"]

Provider preferences (поле provider)

Поле provider управляет тем, как ZvenoAI выбирает upstream-провайдера. Это не часть slug модели и не зависит от vendor в ID модели.

// provider управляет выбором upstream-провайдера (не путайте с vendor в slug модели)
const response = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-4.5',
  provider: {
    order: ['deepinfra', 'novita'], // предпочтительный порядок
    only: ['deepinfra'], // использовать только перечисленные
    ignore: ['novita'], // исключить провайдеров
    allow_fallbacks: true, // можно ли уйти к следующему кандидату
    sort: 'price', // сортировать кандидатов по цене
    require_parameters: true, // только те, кто поддерживает параметры запроса
    quantizations: ['fp16'], // например fp16, int8
    data_collection: 'deny', // только провайдеры без сохранения данных
    // max_price — потолок цены в ₽ за 1000 токенов, не в долларах
    max_price: { prompt: 0.6, completion: 3.0 },
  },
  messages: [{ role: 'user', content: 'Сделай summary.' }],
})

Что означает каждый параметр

order — порядок предпочтения провайдеров. Вместе с allow_fallbacks: false перестаёт быть предпочтением и становится ограничением: маршрут, не названный в списке, не используется вовсе.

only и ignore — оставить только перечисленных провайдеров или, наоборот, исключить их.

allow_fallbacks — можно ли обслужить запрос другим кандидатом, если предпочтительный не подошёл. При false кандидат остаётся один.

sort: "price" — выбирать строго по цене: первым пробуется кандидат с меньшей ценой. Без этого параметра цена тоже учитывается, но мягче — подробнее в разделе «Выбор провайдера по умолчанию».

require_parameters — отсечь провайдеров, которые не поддерживают параметры запроса: стриминг, инструменты, формат ответа.

quantizations — допустимые квантизации весов.

data_collection: "deny" (синоним — zdr: true) — только провайдеры, работающие без сохранения данных. Провайдер, который такого режима не гарантирует, не будет выбран.

max_price — потолок цены за 1000 токенов, отдельно для входа (prompt) и выхода (completion), в рублях.

Выбор провайдера по умолчанию

Без order и sort выбор идёт в два шага.

1. Если у модели есть прямое подключение ZvenoAI к вендору, между ним и агрегатором провайдеров выбирает наш внутренний приоритет маршрутов. Цена на этом шаге не участвует.
2. Если запрос ушёл через агрегатор, провайдера выбирает он, и цена здесь участвует. Сначала отбираются провайдеры без сбоев за последние 30 секунд, затем запросы распределяются между ними с весом, обратным квадрату цены: провайдер вдвое дешевле получает примерно вчетверо больше запросов. Провайдеры со свежими сбоями остаются в резерве — к ним запрос уйдёт, если остальные не ответят.

only и ignore это распределение не отключают, а только сужают круг провайдеров. sort: "price" отменяет оба шага: первым пробуется маршрут с меньшей ценой.

Классы обслуживания

Некоторые провайдеры продают одну модель в нескольких классах обслуживания. Имя провайдера у классов одинаковое, различает их только идентификатор маршрута: класс записан в нём одним из сегментов после косой черты.

• flex — дешевле обычного класса, но запросы идут с низким приоритетом: ответ может прийти заметно позже, запрос может ждать в очереди у провайдера, а при нехватке мощностей провайдер может его отклонить. Подходит для фоновых задач и пакетной обработки, где время ответа не важно.
• priority (у части провайдеров — fast) — дороже, зато запрос обслуживается в первую очередь: задержка ниже и стабильнее, когда провайдер нагружен.
• default или сегмента класса нет вовсе — обычный класс провайдера.

Порядок сегментов у провайдеров разный, поэтому идентификатор не собирайте вручную, а копируйте из раздела «Провайдеры» на странице модели. Там класс подписан рядом с именем провайдера, а маршруты flex и priority стоят отдельной группой под обычными. Там же видно, насколько расходятся цена и задержка классов у конкретной модели, а в панели маршрута есть готовый параметр provider, чтобы закрепить его за своими запросами.

Чтобы запрос шёл только нужным классом, передайте идентификатор маршрута в order и запретите уход к другим маршрутам:

const response = await client.chat.completions.create({
  model: "<модель>",
  provider: {
    order: ["<провайдер>/flex"],
    allow_fallbacks: false,
  },
  messages: [{ role: "user", content: "Разметь отзывы по тональности." }],
});

response = client.chat.completions.create(
    model="<модель>",
    messages=[{"role": "user", "content": "Разметь отзывы по тональности."}],
    extra_body={
        "provider": {
            "order": ["<провайдер>/flex"],
            "allow_fallbacks": False,
        }
    },
)

curl https://api.zveno.ai/v1/chat/completions \
  -H "Authorization: Bearer $ZVENOAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<модель>",
    "provider": {
      "order": ["<провайдер>/flex"],
      "allow_fallbacks": false
    },
    "messages": [{"role": "user", "content": "Разметь отзывы по тональности."}]
  }'

Когда ограничения выполнить нельзя

Если под заданные ограничения не подходит ни один провайдер, запрос отклоняется сразу — кодом 400. Различать случаи проще всего по полю param.

param: "model" — ограничение отсеяло все маршруты у нас. Причина машиночитаема и лежит в metadata.reason:

{
  "error": {
    "code": 400,
    "message": "model openai/gpt-4o-mini has no provider able to honour the requested provider constraints",
    "metadata": { "param": "model", "reason": "no_provider_honors_constraints" }
  }
}

• no_provider_honors_constraints — условие невыполнимо в принципе: запрещённое имя маршрута, требование не сохранять данные, неподходящая квантизация. Смягчите условие.
• no_provider_matches_filters — отсёк потолок цены. Поднимите max_price — и проверьте единицу: значение в рублях за 1000 токенов, долларовый порядок величин отсечёт всё.
• no_provider_supports_streaming, no_provider_supports_tools, no_provider_supports_response_format — ни один маршрут не умеет запрошенного.

param: "provider" — ограничение ушло дальше, и маршрута не нашлось уже там. Поля reason здесь нет:

{
  "error": {
    "code": 400,
    "message": "provider constraints in the request leave no available route for this model",
    "metadata": { "param": "provider" }
  }
}

Так отвечает, например, несуществующее имя провайдера в only. Идентификаторы маршрутов берите из раздела «Провайдеры» на странице модели.

Все эти отказы постоянные: повторный запрос с теми же параметрами вернёт то же самое. Ретрай здесь бесполезен и только жжёт лимиты — менять нужно условие.

Доступные модели

ZvenoAI поддерживает стандартные названия моделей от всех основных провайдеров. Полный список доступных моделей см. в каталоге моделей.

// Используйте формат vendor/model для указания моделей
const models = [
  'openai/gpt-4o', // OpenAI
  'openai/gpt-4o-mini', // OpenAI
  'anthropic/claude-3.5-sonnet', // Anthropic
  'anthropic/claude-opus-4.1', // Anthropic
  'google/gemini-2.5-pro', // Google
  'google/gemini-1.5-flash', // Google
]

// Роутер сам определит провайдера по префиксу vendor

Где смотреть список моделей через API

Публичный список моделей доступен по GET /v1/models. Для embeddings есть отдельный список GET /v1/embeddings/models.

Подробнее: Models API.

Рекомендации

• Для критичных запросов передавайте 2-3 модели разных провайдеров — это повысит доступность вашего сервиса.
• Используйте более дешевые модели (openai/gpt-4o-mini, anthropic/claude-3.5-haiku) для простых задач и сохраняйте бюджет.
• Мониторьте, какие модели чаще используются в ваших запросах — эту статистику можно посмотреть в разделе «Использование».
• Провайдер определяется автоматически по ID модели — вам не нужно указывать его отдельно.

Часто задаваемые вопросы

Как ZvenoAI выбирает модель из массива?

Роутер пробует модели по порядку. Если первая модель доступна — использует её. Если недоступна или возвращает ошибку — переходит к следующей автоматически.

Можно ли указать конкретного провайдера?

Да — через provider.only или provider.order. Без этих параметров провайдера выбирает роутер, и цена в выборе участвует: дешёвые провайдеры получают больше запросов. Подробнее — в разделе «Выбор провайдера по умолчанию». Строгую сортировку по цене включает sort: "price".

Формат slug «vendor/model» (например, openai/gpt-4o) задаёт базовую модель и её вендора — это не то же самое, что провайдер, который обслужит запрос. Какие провайдеры доступны у конкретной модели и сколько стоит каждый, показывает раздел «Провайдеры» на странице модели.

Что если все модели из массива недоступны?

В этом редком случае ZvenoAI вернет ошибку 503 (Service Unavailable). Рекомендуем указывать модели от разных провайдеров для максимальной надежности.