API Documentation

SDK 0.3.4 downloads

Download version 0.3.4 directly from this page. Python requires 3.9 or later; Node.js and local MCP require Node 20 or later. These version-pinned website archives do not imply publication on npm or PyPI. Regular Node SDK users do not need the optional MCP dependencies.

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

List models visible to your API key

Run this read-only request first and copy an exact model code into the examples below. The list shows what the key can see; it does not prove that every operation or mode is enabled for that model.

import os
from routershift import RouterShift

client = RouterShift(api_key=os.environ["ROUTERSHIFT_API_KEY"])
models = client.models.list()
print([model.id for model in models])

Text conversations

Python, Node and MCP can call text models. Agents can keep their primary model and call RouterShift when needed. Model permissions and charges stay in the same API.

import os
from routershift import 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."}],
)
print(response.choices[0].message.content)

HTTP Omni requests

This example sends WAV audio and requests text and audio over an HTTP stream. Choose an accepted OpenAI-compatible route, with stream mode and voice supported by the model. SSE-only models require stream:true; routershift_chat also accepts this option. The SDK preserves content parts, audio, modalities, tool calls and audio responses. HTTP Omni does not provide Realtime WebSockets or arbitrary cross-provider protocol conversion.

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="")

Speech generation

audio.speech calls /v1/audio/speech. Python returns audio bytes; Node returns data bytes and the actual contentType. Choose a voice and format supported by the model. Returned audio is not automatically saved locally. The exact qwen3-tts-flash-2025-11-27 bailian.tts.characters contract is REST-only URL-TTS: submit response_mode=json to /v1/tts or /v1/audio/speech. It returns audio_url, not embedded audio; ordinary SDK byte methods and local MCP audio tools do not support that envelope. Billing evidence is native weighted usage.characters, not local character counts, bytes or playback duration. Seed Audio bills native original_duration, not playback duration or subtitle timing. These contracts still require independent product, pricing, binding and acceptance gates; documentation does not activate drafts.

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 transcription

audio.transcribe submits the explicitly selected audio file as multipart to /v1/audio/transcriptions. Keep its actual filename extension. This example requests JSON and reads text; supported languages and formats depend on the route.

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)

Transcribe an HTTPS audio URL

Use audio.transcribe_url in Python, audio.transcribeURL in Node.js, or POST JSON to /v1/transcriptions with file_url. The SDK validates the HTTPS URL and does not download the recording locally. FunASR/Qwen ASR public JSON returns segments/words only when valid native timing is present. Their start/end values are seconds converted from native milliseconds; missing or invalid timing is not invented and is marked by timestamps_omitted. Subtitle timing and playback duration are not billing evidence: billing uses the contract's native final or cumulative duration, without summing cumulative reports. Missing or conflicting evidence requires reconciliation, not resubmission. The Go and Java tabs use their standard HTTP clients; RouterShift does not claim first-party Go or Java SDKs.

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)

Generate images and read image tasks

Use images.generate with a model enabled for image generation. On models that support asynchronous images, add async_=True in Python or async: true in Node.js, then query the returned id with images.retrieve. A completed response contains data with image URLs; a pending response contains an id and 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))

Submit a video and query its status

videos.create submits one video task and returns task_id. Save it before querying videos.retrieve; a pending task may not have video_url yet. Both SDKs also provide videos.poll for bounded waiting. The API path is /v1/video/generations, with singular video.

Verified native Seedance and Wan 3.0 routes support generate_audio: omit it for the provider default, false for no audio track, true for audio. Wan maps it to parameters.audio and currently defaults to sound. Audio on/off uses the same Wan video tariff, without an extra audio charge. Other routes may not support it; explicit values must not be silently dropped.

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)

Add model tools to an Agent

Add tools to an Agent through MCP, or use the Python/Node SDK in application code: these are parallel access options. Follow these four local stdio steps and keep credentials out of shared configuration and version control.

1. 1. Create a dedicated directory and install MCP

   Use Node 20 or later. This MCP-only installation adds the two protocol peer dependencies; a regular Node SDK installation does not need them.

   shell

   Copy

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

2. 2. Resolve the absolute server entry

   Run this in the new directory. It prints a JSON-escaped absolute path that you can paste into the configuration args array.

   Node.js

   Copy

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

3. 3. Configure the local stdio client

   Replace the example path, set the API key only in your local environment, and keep the trusted API origin without /v1, credentials, a query or fragment. The Codex tab uses its documented stdio and env_vars syntax.

   mcpServers JSONCodex TOML

   Copy

   {
     "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. Restart the connector and verify eight tools

   Restart or reload the MCP client, confirm that all eight tools appear, then call the read-only routershift_list_models first. Invoke a billed model tool only when you intend to submit that operation.

Eight tools are available: routershift_list_models, routershift_chat, routershift_generate_image, routershift_create_video, routershift_get_task, routershift_speech, routershift_transcribe, routershift_transcribe_url. First select a model supporting the operation. Query image/video tasks with routershift_get_task, supplying kind (image or video) and task_id.

routershift_chat accepts HTTPS image/video references; audio_file reads an explicitly selected absolute WAV/MP3 path, up to 16 MiB. routershift_transcribe reads one selected local audio file through file_path; routershift_transcribe_url passes one HTTPS file_url without downloading it. Speech and Omni audio outputs return inline audio. routershift_generate_image accepts response_format url or b64_json; for bounded, valid PNG, JPEG, WebP or GIF b64_json output, it returns MCP-native image content without writing, downloading or rehosting a file, and without copying Base64 into text JSON. Oversize or unknown-format image data is explicitly omitted; do not resubmit a paid request to retrieve omitted output. The adapter does not scan directories or automatically save results.

The JSON tab shows the common mcpServers shape; the TOML tab shows documented Codex syntax. Configuration locations and subprocess permissions differ by client. Remote-only MCP clients need a separately supported transport; these examples do not claim testing in every Agent UI.

The local MCP adapter lets Agents call RouterShift text, multimodal, audio and task APIs. The existing /v1/mcp gateway provides access to configured external tools. Its HTTP/SSE configuration does not replace the local model-tool configuration here.