Документация

При создании задайте лимит в рублях и срок: 1, 7, 30, 90 дней или бессрочно. Срок отсчитывается от создания ключа. После его окончания новые запросы с этим ключом недоступны. Создайте новый ключ и обновите переменную окружения приложения.

curl https://router.znatalk.ai/v1/chat/completions \
  -H "Authorization: Bearer $ZNATALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-flash", "max_tokens":512,
       "messages":[{"role":"user","content":"Привет!"}]}'

В DEV используйте https://dev.router.znatalk.ai/v1 и ключ тестового окружения. Ключи и балансы окружений раздельны. Доступность моделей зависит от подключённых поставщиков.

Для Messages базовый адрес указывается без /v1. Назначьте модель каждому уровню. Совместимость Claude Code с моделями других лабораторий может меняться при обновлении клиента.

export ANTHROPIC_BASE_URL=https://router.znatalk.ai
export ANTHROPIC_AUTH_TOKEN=$ZNATALK_KEY
export ANTHROPIC_MODEL=deepseek/deepseek-v4-pro
export ANTHROPIC_DEFAULT_OPUS_MODEL=$ANTHROPIC_MODEL
export ANTHROPIC_DEFAULT_SONNET_MODEL=$ANTHROPIC_MODEL
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek/deepseek-flash
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0
claude

Укажите CLAUDE_CODE_MAX_CONTEXT_TOKENS по значению context_length выбранной модели. Серверные инструменты, strict, output_config.format и stop_sequences возвращают 400. Параметры thinking, cache_control, context_management и metadata принимаются, но не управляют поставщиком.

Добавьте Router в opencode.json. Провайдер @ai-sdk/openai-compatible использует Chat Completions.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "router": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Router",
      "options": {
        "baseURL": "https://router.znatalk.ai/v1",
        "apiKey": "{env:ZNATALK_KEY}"
      },
      "models": {
        "deepseek/deepseek-flash": { "name": "DeepSeek" }
      }
    }
  }
}

Сохраните ключ в ZNATALK_KEY и выберите модель через /models. Проверьте её доступность в GET /v1/models. Пакет @ai-sdk/openai для режима Responses здесь не подходит.

В настройках выберите провайдера OpenAI Compatible. Он использует Chat Completions. Укажите ключ Router и параметры подключения:

Base URL: https://router.znatalk.ai/v1
Model ID: deepseek/deepseek-flash

Размер контекста, поддержку изображений и инструментов задайте по возможностям выбранной модели.

Добавьте модель в config.yaml, заменив YOUR_ROUTER_KEY своим ключом. Используйте Chat Completions:

name: Router
version: 1.0.0
schema: v1
models:
  - name: DeepSeek
    provider: openai
    model: deepseek/deepseek-flash
    apiBase: https://router.znatalk.ai/v1
    apiKey: YOUR_ROUTER_KEY
    useResponsesApi: false
    useLegacyCompletionsEndpoint: false

Этот пример подключает чат. Режимы Responses и legacy Completions Router не обслуживает.

В настройках подключений добавьте OpenAI-совместимый API и ключ Router. Выберите режим Chat Completions, отключите Responses:

URL: https://router.znatalk.ai/v1
API Key: YOUR_ROUTER_KEY

Обновите список моделей и выберите доступную вашему ключу.

Ответ имеет тип text/event-stream: JSON в строках data:, в конце data: [DONE]. Комментарий : keep-alive поддерживает соединение, пока модель думает. До принятия запроса поставщиком ошибка сохраняет HTTP-статус; после принятия ошибка может прийти внутри потока. Сохраняйте x-request-id для проверки результата.

total_cost выражен в рублях, currency равна RUB. cost_status: known означает известную сумму, zero означает подтверждённый ноль. null не означает бесплатный запрос: расчёт может быть ещё не завершён.

Для бухгалтерской сверки используйте decimal-парсер: JSON-числа могут содержать больше знаков, чем сохраняет JavaScript Number. Исправления отражаются в adjustments и receipt_revision. Метод /v1/generation/changes?after=0 возвращает изменения и следующий cursor.

max_tokens ограничивает ответ и резерв. Если заданный лимит не помещается в баланс, API вернёт 402. Если лимит не задан, Router подбирает доступный объём в пределах модели; фактический предел передаётся в x-max-tokens.

В балансе available уже учитывает резерв, reserved показывает его отдельно. total_usage содержит списания, total_credits содержит зачисления. При задолженности debt новые запросы недоступны.

# Сохраните operation_id в вашей системе до отправки.
reply = client.chat.completions.create(
    model="deepseek/deepseek-flash",
    max_tokens=512,
    messages=[{"role": "user", "content": "Привет!"}],
    extra_headers={"Idempotency-Key": operation_id},
)

После таймаута сначала запросите GET /v1/generation?idempotency_key=OPERATION_ID с тем же ключом API. Передавайте либо id, либо idempotency_key, не оба сразу.

Повтор Chat Completions с тем же ключом возвращает запись запроса: 200 для завершённого или 202 для незавершённого. Исходный текст ответа не воспроизводится. Для Messages повтор возвращает 409 idempotency_replay; результат также проверяется через /v1/generation.

В первом примере автоматические повторы SDK отключены. Не повторяйте запрос при x-should-retry: false. Если повтор допустим, соблюдайте Retry-After и сохраняйте исходный ключ операции.

400

Проверьте параметры и возможности модели.

401 / 403

Проверьте ключ и доступ к модели.

402

Пополните баланс или уменьшите лимит ответа.

409

Проверьте запись исходного запроса.

429

Снизьте частоту, учитывайте Retry-After.

5xx

Проверьте x-should-retry и запись запроса перед повтором.

API обычно возвращает error.code, error.message и error.request_id. Ошибки разбора URL и превышения размера тела могут иметь другой формат.

pricing.prompt и pricing.completion содержат десятичные строки: рубли за один токен. Умножьте на миллион для сравнения привычных тарифов. Поле route_version обозначает версию маршрута.

GET /v1/models/endpoints?model=MODEL_ID с ключом показывает доступные маршруты и их цены. GET /v1/stats/latency показывает p50, p90 и p99 первого содержательного фрагмента за час и сутки. Это время от отправки поставщику, а не накладные расходы Router. При малом числе наблюдений процентили равны null.

Содержимое запроса передаётся поставщику выбранной модели, в том числе за пределы России. Параметры provider.only, ignore, order и allow_fallbacks проверяются по тегу хоста из /models/endpoints. Для текста и векторов запасной хост той же модели используется только если запрос точно не был отправлен. После отправки автоматического повторного запроса нет.

Изображения, аудио и файлы в сообщениях передаются встроенными данными, например data: URL. Удалённые URL и ссылки на загруженные файлы отклоняются с remote_content_unsupported. Поддержка конкретного формата зависит от модели.

provider.country (например, RU) и provider.quantizations (например, ["bf16"]) ограничивают выбор хостами с документированными сведениями оператора. Если подходящего хоста нет, запрос отклоняется. Другую модель Router не подставляет.

Без provider выбор автоматический. В provider.onlyукажите одного или нескольких допустимых поставщиков. Один запрос выполняется у одного поставщика. Яндекс поддерживает поиск с depth: basic; Tavily также поддерживает advanced и чтение страниц.

Для предварительного расчёта используйте POST /tools/search/quote, /tools/read-url/quote или /tools/code/quote. Полученный quote_id можно передать при выполнении. Оценка не является списанием. В ответе usage.cost содержит стоимость строкой, currency равна RUB. Неизвестная стоимость не означает ноль.

В Chat Completions объявите только нужные инструменты. Router выполнит вызовы и передаст результаты модели. Обычный запрос без этих объявлений инструменты не запускает.

reply = client.chat.completions.create(
    model="deepseek/deepseek-flash",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Найди актуальный курс ЦБ"}],
    extra_headers={"Idempotency-Key": os.environ["REQUEST_ID"]},
    extra_body={
        "tools": [{"type": "router:web_search",
                   "provider": {"only": ["yandex", "tavily"]}}],
        "server_tool_limit": 10,
    },
)

Типы: router:web_search, router:read_url, router:code_execution. Лимит server_tool_limitпо умолчанию 30, допустимо от 1 до 256. Клиентские function tools можно объявить рядом: при таком вызове Router вернёт обычный tool_calls клиенту. Вызовы выполняются последовательно. Формат Messages не поддерживается. Итоговая стоимость включает работу модели и инструментов.

Daytona выполняет Python в изолированной среде с доступом к публичным пакетам и файлам. Передайте session_id, чтобы продолжить работу с переменными и файлами. Сессия принадлежит вашему аккаунту. Автоматические вызовы модели используют отдельную сессию в рамках запроса.

Сессию можно открыть через POST /v1/tools/code/sessions. Загрузка: POST /v1/tools/code/sessions/ID/files, байты файла в теле, параметры name и sha256 в query string. Передайте полученные идентификаторы в files при исполнении. Для скачивания используйте GET /v1/tools/code/files/FILE_ID, для закрытия сессии: DELETE /v1/tools/code/sessions/ID. Все операции требуют авторизацию.

Tavily и Daytona обрабатывают данные за пределами России. Выбор Яндекса для поиска не меняет поставщика чтения страниц или исполнения Python.

Для подключённых моделей доступны POST /audio/transcriptions, POST /audio/speech, POST /images/generations и POST /videos. В GET /models передайте kind=transcription|speech|image|video. Пустой каталог означает, что доступных моделей этого типа пока нет.

Распознавание принимает WAV PCM через multipart. Синтез возвращает MP3 и считает символы. Изображения возвращаются в base64. Видео проверяется через GET /videos/{id}, готовый файл: GET /videos/{id}/content.

Публичные /responses, /messages/count_tokens и realtime пока недоступны. Не каждый OpenAI-совместимый инструмент использует Chat Completions: проверьте выбранный им метод.