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 是 Agent 的 stdio 入口。自有 SDK 的 Base URL 使用不带 /v1 的 origin。厂商 SDK 可能需要字段映射和重试调整，不能承诺只换 Key 或 Base URL 即兼容多模态。还需对齐脱敏请求／响应样例与预期结果；先用合成响应验证 200／202、GET 待完成、SSE 不完整、提交未知和重复交付，真实付费验收另需明确授权与预算。

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

列出 API Key 可见的模型

请先运行这个只读请求，再把返回的准确模型代码复制到下方示例。列表只说明该密钥可以看见哪些模型，不证明每个模型已启用全部操作或模式。

使用实际执行的同一 Key 读取 GET /v1/models?details=1：不创建任务、不预留资金、不调用供应商，认证、日志和限流仍适用。逐项查看 details.operations 的端点／模式、constraints.status 与 import_contract.status/reason，完整保留维度、条件、币种、精度、selector、观察时间及 semantic_sha256。参考价格不等于可执行合同；限制缺失／未知不等于无限制，available 也不保证资金可用。当前不是完整的每模型输入 Schema，也不代表非 Token 合同已统一投影。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() 及 models.list 的 details=true 选项；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 SDK 与 MCP 都可调用文本模型。Agent 可以继续使用自己的主模型，按需调用 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)

通过 HTTP 调用 Omni 模型

下例使用 WAV 音频输入，并通过 HTTP 流式响应请求文本和音频输出。请选用已验收的 OpenAI 兼容路由，按模型支持选择 stream 和音色；仅支持 SSE 的模型必须使用 stream:true，MCP 的 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。请使用模型支持的音色和格式；返回音频不会自动保存到本地。精确 qwen3-tts-flash-2025-11-27 的 bailian.tts.characters 合同是仅支持 REST 的 URL-TTS：向 /v1/tts 或 /v1/audio/speech 提交 response_mode=json，返回 audio_url 而非内嵌音频，普通 SDK 字节方法及本地 MCP 音频工具不支持此返回形式。其计费证据是原生加权 usage.characters，不能用本地字符数、字节数或播放时长替代。Seed Audio 的计费量是原生 original_duration，不是播放 duration 或字幕时间。上述合同仍须独立完成商品、报价、绑定和验收；文档不代表草稿已激活。

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

Python 使用 audio.transcribe_url，Node.js 使用 audio.transcribeURL；也可向 /v1/transcriptions 直接提交含 file_url 的 JSON。SDK 只校验 HTTPS URL，不在本地下载录音。FunASR/Qwen ASR 的公有 JSON 仅在原生回执提供有效时间信息时返回 segments/words；start/end 以秒表示，由原生毫秒转换，缺失或无效时间不补造，并以 timestamps_omitted 标记。字幕时间和播放时长不是计费证据；计费使用该合同的原生最终或累计 duration，累计报告不相加，缺失或冲突需对账，不重发请求。Go 与 Java 标签使用各自标准 HTTP 客户端；RouterShift 不宣称提供自有 Go 或 Java SDK。

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 调用已启用生图能力的模型。支持异步图片的模型可在 Python 中添加 async_=True，在 Node.js 中添加 async: true，再用返回的 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。请先保存任务 ID，再用 videos.retrieve 查询；等待中的任务可能尚无 video_url。两个 SDK 也提供 videos.poll 进行有期限的等待。API 路径为 /v1/video/generations，其中 video 为单数。

已验证的原生 Seedance 与 Wan 3.0 路由支持 generate_audio：不填写保留上游默认值，false 无音轨，true 有音轨。Wan 映射为 parameters.audio，当前默认有声，开关声音使用相同视频价格，不另加音频计费。其他路由不保证支持，不能静默删掉显式值。

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)

为 Agent 添加模型工具

可通过 MCP 给 Agent 添加工具，也可在应用代码中使用 Python/Node SDK，两者是并列接入方式。请按下面四步配置本地 stdio，并避免把凭据放入共享配置或版本控制。

1. 1. 建立独立目录并安装 MCP

   请使用 Node 20 或更高版本。此 MCP 专用安装会加入两个协议对等依赖；普通 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 Key，并保留可信 API origin，不要添加 /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；对大小受限且格式有效的 PNG、JPEG、WebP 或 GIF b64_json 输出，会返回 MCP 原生 image content，不写入、下载或转托管文件，也不会把 Base64 塞进文本 JSON。超限或未知格式的图片数据会被明确省略；不要为取回被省略的输出重发付费请求。适配器不扫描目录，也不自动保存结果。

JSON 标签展示常见的 mcpServers 结构；TOML 标签展示 Codex 文档规定的语法。不同客户端的配置位置与子进程权限不同；仅支持远程 MCP 的客户端需要另行支持的传输方式。这些示例不宣称已在所有 Agent 界面实测。

本地 MCP 适配器让 Agent 调用 RouterShift 的文本、多模态、音频和任务查询 API。平台现有 /v1/mcp 网关用于接入已配置的外部工具，其 HTTP/SSE 配置不能替代此处的本地模型工具配置。