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

Версия 1.0 · База: https://route.nomadhost.xyz/v1

Быстрый старт

NomadRoute говорит на протоколе OpenAI: достаточно указать другой base_url и ключ NomadRoute.

Python (openai)

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://route.nomadhost.xyz/v1",
    api_key="nr-live-ВАШ_КЛЮЧ",
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Привет! Расскажи о себе в двух словах."}],
)
print(response.choices[0].message.content)
print(response.nomadroute.request_id, response.nomadroute.cost_usd)

JavaScript (openai-node)

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://route.nomadhost.xyz/v1",
  apiKey: process.env.NOMADROUTE_API_KEY,
});

const response = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "Привет!" }],
});
console.log(response.choices[0].message.content);

cURL

curl https://route.nomadhost.xyz/v1/chat/completions \
  -H "Authorization: Bearer nr-live-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

Base URL и API-ключ

Ключ создаётся в личном кабинете и показывается один раз. Передавайте его в заголовке:

Authorization: Bearer nr-live-...

Модели

Список моделей с ценами и возможностями: GET /v1/models и страница «Модели и цены».

curl https://route.nomadhost.xyz/v1/models \
  -H "Authorization: Bearer nr-live-ВАШ_КЛЮЧ"

Цены указаны за 1 000 000 токенов в USD. Если для модели задана скидка, она применяется автоматически ко всем типам токенов (вход, выход, кешированные).

Автоматическая маршрутизация

Поле model управляет выбором модели:

Режим выбирается отдельно для каждого API-запроса значением поля model; настройки в кабинете не влияют на маршрутизацию.

Chat Completions

POST /v1/chat/completions — совместим с OpenAI Chat Completions API.

Ответ

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "claude-sonnet-5",
  "choices": [
    {"index": 0, "message": {"role": "assistant", "content": "..."}, "finish_reason": "stop"}
  ],
  "usage": {
    "prompt_tokens": 128,
    "completion_tokens": 64,
    "total_tokens": 192,
    "prompt_tokens_details": {"cached_tokens": 0}
  },
  "nomadroute": {
    "request_id": "req_...",
    "model": "claude-sonnet-5",
    "mode": "auto",
    "attempts": 1,
    "cost_usd": 0.0009,
    "provider_cost_usd": 0.0009,
    "discount_usd": 0.0
  }
}

Идентификатор запроса также возвращается в заголовке x-request-id — указывайте его в обращении в поддержку.

Потоковая генерация

stream = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Напиши короткое стихотворение"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")
    if chunk.usage:
        print("\\nтокены:", chunk.usage.prompt_tokens, chunk.usage.completion_tokens)

Перед data: [DONE] приходит финальный чанк с usage и объектом nomadroute (стоимость запроса).

Инструменты

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Какая погода в Москве?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Погода в городе",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
)
# response.choices[0].message.tool_calls

Ошибки

Формат ошибок совместим с OpenAI:

{"error": {"message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request"}}

Биллинг

• Оплата — по фактическому использованию токенов после выполнения запроса.
• Учитываются отдельно: входные, выходные и кешированные входные токены.
• Стоимость считается по тарифам NomadRoute (они могут отличаться от цен провайдеров) с учётом скидки модели.
• Перед дорогим запросом проверяется предполагаемая стоимость: при недостатке баланса возвращается 402.
• Баланс не может стать отрицательным — списание атомарно и условно.
• Отменённые и ошибочные запросы не тарифицируются; история операций — в кабинете.
• Повторный запрос с тем же Idempotency-Key и тем же телом возвращает сохранённый результат без повторного списания.

curl https://route.nomadhost.xyz/v1/chat/completions \
  -H "Authorization: Bearer nr-live-..." \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "..."}]}'

Лимиты

• Ограничения частоты задаются тарифом: запросов в минуту/день, токенов в минуту/день, параллельных запросов.
• Максимальный размер тела запроса — 1 МБ.
• До 200 сообщений и 64 инструментов в запросе.
• Каждый API-ключ может иметь собственный лимит бюджета; при его исчерпании ключ автоматически отзывается.

Обратная связь

curl https://route.nomadhost.xyz/v1/feedback \
  -H "Authorization: Bearer nr-live-..." \
  -H "Content-Type: application/json" \
  -d '{"request_id": "req_...", "rating": 1, "comment": "Отличный ответ"}'

# rating: 1 — полезно, -1 — нет (одна оценка на запрос, можно изменить)

Вопросы: [email protected]