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

Загрузки Python 0.3.7 и Node 0.3.7

Загрузки фиксированных версий на этой странице соответствуют Python 0.3.7 и Node 0.3.7 и включают подробное обнаружение моделей. Требуется Python 3.9 или новее; Node.js и локальный MCP требуют Node 20 или новее. Архивы не означают публикацию в npm или PyPI. Обычному Node SDK необязательные зависимости MCP не нужны.

Исходный код клиента и учётные данные поставщика не нужны. Укажите язык/среду и версию SDK, model_code + operation + mode, обезличенные параметры, ограничения медиа и срок URL, восстановление, бюджет по валюте и параллельность. REST — контракт выполнения; SDK — необязательные тонкие клиенты, локальный MCP — вход stdio для агентов. Собственный SDK использует источник без /v1. SDK поставщика может требовать изменения полей и повторов; замена только ключа или базового URL не гарантирует мультимодальную совместимость. Согласуйте обезличенные примеры запросов/ответов и ожидаемые результаты. Сначала проверьте синтетические 200/202, ожидающий GET, неполный SSE, неизвестную отправку и повторную доставку; платная приёмка требует отдельного разрешения и явного бюджета.

python -m pip install "https://routershift.com/downloads/sdk/routershift-0.3.7-py3-none-any.whl"

Показать модели, видимые вашему API-ключу

Сначала выполните этот запрос только для чтения и скопируйте точный код модели в примеры ниже. Список показывает, что видит ключ; он не подтверждает, что для модели включены все операции или режимы.

Используйте тот же рабочий ключ для GET /v1/models?details=1: задачи не создаются, средства не резервируются, поставщик не вызывается; авторизация, журналы и лимиты сохраняются. Проверяйте пути/режимы details.operations, constraints.status и import_contract.status/reason. Сохраняйте измерения, условия, валюту, точность, селекторы, время наблюдения и semantic_sha256. Справочная цена не равна исполнимому контракту. Отсутствующие/неизвестные ограничения не означают неограниченный ввод; available не гарантирует средства. Это не полная Schema ввода и не универсальная проекция нетокенных контрактов. models.list() по умолчанию остаётся обычным списком; явно запрашивайте подробности включёнными методами SDK или через REST. Для constraints значение available описывает проверенное подмножество операции; unsupported требует отдельного руководства.

Различайте details.constraints.operations[].scope: reviewed_subset — проверенное подмножество операции; finite_admission_opt_in относится только к явно ограниченным запросам, а не ко всему обычному чату. parameters — не полная Schema ввода. При наличии details.admission проверяйте status, profile, /details/admission/required_headers и объявленные пределы ввода/вывода; неизвестные модели остаются unavailable. Обнаружение не предоставляет средства или универсальный предел цены.

Node 0.3.7 включает listDetails() и параметр details=true для models.list; Python 0.3.7 включает models.list(details=True) и list_details(). Эти методы подробного обнаружения входят в пакеты данной версии. models.list() по умолчанию остаётся обычным списком; старые установки не получают новые методы автоматически.

curl --fail-with-body --connect-timeout 10 --max-time 30 "https://api.routershift.com/v1/models?details=1" \
  -H "Authorization: Bearer $ROUTERSHIFT_API_KEY"

Текстовые диалоги

Python, Node и MCP могут вызывать текстовые модели. Агент может сохранить основную модель и обращаться к RouterShift по мере необходимости. Права и списания остаются в той же API.

import os
from routershift import RequestOptions, RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
response = client.chat.completions.create(
    model="YOUR_TEXT_MODEL_CODE",
    messages=[{"role": "user", "content": "Summarize this project in one sentence."}],
    request_options=RequestOptions(max_retries=0),
)
print(response.choices[0].message.content)

Запросы Omni по HTTP

Пример передаёт WAV-аудио и запрашивает текст и звук через поток HTTP. Выберите проверенный маршрут, совместимый с OpenAI, с поддерживаемыми моделью режимом stream и голосом. Для моделей только с SSE требуется stream:true; routershift_chat тоже принимает этот параметр. SDK сохраняет блоки содержимого, audio, modalities, вызовы инструментов и аудиоответы. HTTP Omni не предоставляет Realtime WebSocket или произвольное преобразование протоколов поставщиков.

import base64
import os
from pathlib import Path
from routershift import RequestOptions, RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
audio_data = base64.b64encode(Path("/absolute/path/to/sample.wav").read_bytes()).decode()
response = client.chat.completions.create(
    model="YOUR_OMNI_MODEL_CODE",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Describe the sound."},
        {"type": "input_audio", "input_audio": {"data": audio_data, "format": "wav"}},
    ]}],
    stream=True,
    modalities=["text", "audio"],
    audio={"voice": "YOUR_MODEL_VOICE", "format": "wav"},
    request_options=RequestOptions(max_retries=0),
)
for chunk in response:
    if chunk.choices:
        delta = chunk.choices[0].delta or {}
        print(delta.get("content", ""), end="")
        if delta.get("audio"):
            print(delta["audio"].get("transcript", ""), end="")

Синтез речи

audio.speech вызывает /v1/audio/speech. Python возвращает байты аудио; Node — байты data и фактический contentType. Выберите поддерживаемые моделью голос и формат. Аудио не сохраняется автоматически в локальный файл.

import os
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
speech = client.audio.speech(
    model="YOUR_SPEECH_MODEL_CODE",
    input="Welcome to RouterShift.",
    voice="YOUR_MODEL_VOICE",
    response_format="wav",
)
print(len(speech))

Расшифровка аудио

audio.transcribe отправляет явно выбранный аудиофайл как multipart в /v1/audio/transcriptions. Сохраните фактическое расширение файла. Пример запрашивает JSON и читает text; языки и форматы зависят от маршрута.

import os
from pathlib import Path
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
transcript = client.audio.transcribe(
    model="YOUR_TRANSCRIPTION_MODEL_CODE",
    file=Path("/absolute/path/to/sample.wav").read_bytes(),
    filename="sample.wav",
    response_format="json",
)
print(transcript.text)

Расшифровка аудио по HTTPS-URL

Используйте audio.transcribe_url в Python, audio.transcribeURL в Node.js или отправьте JSON с file_url в /v1/transcriptions. SDK проверяет HTTPS-URL и не загружает запись локально. Вкладки Go и Java используют стандартные HTTP-клиенты этих языков; RouterShift не заявляет о собственных SDK для Go или Java.

import os
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
transcript = client.audio.transcribe_url(
    "YOUR_TRANSCRIPTION_MODEL_CODE",
    "https://media.example/recording.wav",
    language="en",
    audio_format="wav",
    response_format="json",
)
print(transcript.text)

Создание изображений и проверка задач

Используйте images.generate с моделью, для которой включена генерация изображений. Для моделей с асинхронными изображениями добавьте async_=True в Python или async: true в Node.js, затем передайте полученный id в images.retrieve. Готовый ответ содержит data с URL изображений, а ожидающий — id и status.

import os
from routershift import ImageTaskResponse, RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
image = client.images.generate(
    model="YOUR_IMAGE_MODEL_CODE",
    prompt="A quiet garden in watercolor",
)
print(image)
if isinstance(image, ImageTaskResponse):
    print(client.images.retrieve(image.id))

Отправка видео на генерацию и проверка статуса

videos.create создаёт одну задачу генерации видео и возвращает task_id. Сохраните его перед вызовом videos.retrieve; у ожидающей задачи video_url может пока отсутствовать. Оба SDK также предоставляют videos.poll для ожидания с ограничением времени. Путь API — /v1/video/generations, слово video в единственном числе.

Проверенные нативные маршруты Seedance и Wan 3.0 поддерживают generate_audio: отсутствие поля сохраняет настройку поставщика, false убирает звуковую дорожку, true включает её. Wan преобразует поле в parameters.audio; по умолчанию звук сейчас включён. Тариф видео Wan одинаков со звуком и без него, без отдельной платы за аудио. Другие маршруты могут не поддерживать поле; явно заданные значения нельзя незаметно удалять.

import os
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
task = client.videos.create(
    model="YOUR_VIDEO_MODEL_CODE",
    prompt="A slow camera movement through a garden",
)
print(task.task_id)
result = client.videos.retrieve(task.task_id)
print(result.status, result.video_url)

Добавить инструменты моделей агенту

Добавляйте инструменты агенту через MCP или используйте Python/Node SDK в приложении: это параллельные способы подключения. Выполните четыре шага локальной настройки stdio и не сохраняйте учётные данные в общих конфигурациях или системе контроля версий.

1. 1. Создать отдельный каталог и установить MCP

   Используйте Node 20 или новее. Эта установка только для MCP добавляет две peer-зависимости протокола; обычной установке Node SDK они не нужны.

   shell

   Копировать

   mkdir routershift-mcp
   cd routershift-mcp
   npm init -y
   npm install "https://routershift.com/downloads/sdk/routershift-sdk-0.3.7.tgz" @modelcontextprotocol/server@2.0.0 zod@4.6.4

2. 2. Получить абсолютный путь к серверу

   Выполните команду в новом каталоге. Она выводит абсолютный путь с экранированием JSON, который можно вставить в массив args конфигурации.

   Node.js

   Копировать

   node -p "JSON.stringify(require('node:path').resolve('node_modules/@routershift/sdk/dist/mcp/cli.js'))"

3. 3. Настроить локальный клиент stdio

   Замените пример пути, задайте API-ключ только в локальном окружении и сохраните доверенный origin API без /v1, учётных данных, строки запроса или фрагмента. На вкладке Codex используется документированный синтаксис stdio и env_vars.

   mcpServers JSONCodex TOML

   Копировать

   {
     "mcpServers": {
       "routershift": {
         "command": "node",
         "args": [
           "/absolute/path/to/your/project/node_modules/@routershift/sdk/dist/mcp/cli.js"
         ],
         "env": {
           "ROUTERSHIFT_API_KEY": "sk-REPLACE_LOCALLY",
           "ROUTERSHIFT_BASE_URL": "https://api.routershift.com"
         }
       }
     }
   }

4. 4. Перезапустить коннектор и проверить десять инструментов

   Перезапустите или перезагрузите клиент MCP, убедитесь, что видны все десять инструментов, и сначала вызовите routershift_list_models только для чтения. Вызывайте оплачиваемый инструмент модели, только когда намерены отправить соответствующую операцию.

Доступны десять инструментов: routershift_list_models, routershift_estimate_chat, routershift_chat, routershift_generate_image, routershift_create_video, routershift_get_task, routershift_get_request, routershift_speech, routershift_transcribe, routershift_transcribe_url. Сначала выберите модель для нужной операции. Проверяйте задачи изображений и видео через routershift_get_task, передавая kind (image или video) и task_id. Запрашивайте квитанцию запроса через routershift_get_request с request_id только для чтения; это не отправляет и не активирует платную операцию. В 0.3.7 details:true читает подробные модели и договоры. routershift_estimate_chat только читает конечную верхнюю границу допуска: без вызова поставщика, резервирования и автоматического исполнения; funds_verified=false. Оценка не является итоговым счётом или разрешением на вызов.

routershift_chat принимает HTTPS-ссылки на изображения и видео; audio_file читает явно выбранный абсолютный путь WAV/MP3 размером до 16 MiB. routershift_transcribe читает выбранный локальный аудиофайл через file_path; routershift_transcribe_url передаёт HTTPS file_url без загрузки. Речь и аудио Omni возвращаются встроенными. routershift_generate_image принимает response_format url или b64_json; для ограниченного по размеру корректного вывода b64_json в формате PNG, JPEG, WebP или GIF он возвращает нативное содержимое image MCP, не записывая, не загружая и не размещая файл и не копируя Base64 в текстовый JSON. Слишком большие данные или неизвестный формат явно пропускаются; не отправляйте платный запрос повторно для получения пропущенного вывода. Адаптер не сканирует каталоги и не сохраняет результаты автоматически.

На вкладке JSON показана распространённая структура mcpServers; на вкладке TOML — документированный синтаксис Codex. Расположение конфигурации и права на дочерние процессы зависят от клиента. Клиентам только с удалённым MCP нужен отдельно поддерживаемый транспорт; эти примеры не заявляют проверку во всех интерфейсах агентов.

Локальный адаптер MCP позволяет вызывать API RouterShift для текста, мультимодальности, аудио и задач. Существующий шлюз /v1/mcp предоставляет доступ к настроенным внешним инструментам. Его конфигурация HTTP/SSE не заменяет приведённую здесь локальную конфигурацию инструментов моделей.