Documentación de la API

Descargas de Python 0.3.7 y Node 0.3.7

Las descargas de versión fija de esta página corresponden a Python 0.3.7 y Node 0.3.7 e incluyen el descubrimiento detallado de modelos. Se requiere Python 3.9 o posterior; Node.js y MCP local requieren Node 20 o posterior. Estos archivos no implican publicación en npm o PyPI. El SDK Node normal no necesita dependencias MCP opcionales.

No se necesitan el código fuente del cliente ni credenciales del proveedor. Comparta lenguaje/entorno y versión del SDK, model_code + operation + mode, parámetros anonimizados, límites multimedia y caducidad de URL, recuperación, presupuesto por moneda y concurrencia. REST es el contrato de ejecución; los SDK son clientes ligeros opcionales y MCP local es una entrada stdio para agentes. El SDK propio usa un origen sin /v1. Un SDK del proveedor puede necesitar ajustes de campos y reintentos; cambiar solo la clave o URL base no garantiza compatibilidad multimodal. Acuerde muestras anónimas de solicitud/respuesta y resultados esperados. Pruebe primero respuestas sintéticas 200/202, GET pendiente, SSE incompleto, envío desconocido y entrega duplicada; la aceptación de pago requiere autorización y presupuesto explícitos.

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

Listar modelos visibles para su clave API

Ejecute primero esta solicitud de solo lectura y copie un código de modelo exacto en los ejemplos siguientes. La lista muestra lo que puede ver la clave; no confirma que cada operación o modo esté habilitado para ese modelo.

Consulte GET /v1/models?details=1 con la misma clave de ejecución: no crea tareas, reserva fondos ni llama al proveedor; siguen aplicándose autenticación, registros y límites. Revise rutas/modos de details.operations, constraints.status e import_contract.status/reason. Conserve dimensiones, condiciones, moneda, precisión, selectores, hora de observación y semantic_sha256. El precio de referencia no es un contrato ejecutable. Los límites ausentes/desconocidos no permiten entradas ilimitadas; available no garantiza fondos. No es un Schema de entrada completo ni una proyección universal de contratos sin tokens. models.list() sigue siendo la lista normal por defecto; solicite detalles explícitos con los métodos incluidos en el SDK o REST. En constraints, available describe el subconjunto revisado de la operación; unsupported requiere la guía específica.

Distinga details.constraints.operations[].scope: reviewed_subset es un subconjunto revisado de la operación; finite_admission_opt_in solo afecta a solicitudes con límite finito explícito, no a todo chat normal. parameters no es un Schema completo de entrada. Si existe details.admission, revise status, profile, /details/admission/required_headers y los límites declarados de entrada/salida; los modelos desconocidos siguen unavailable. El descubrimiento no concede fondos ni un límite de precio universal.

Node 0.3.7 incluye listDetails() y la opción details=true de models.list; Python 0.3.7 incluye models.list(details=True) y list_details(). Estos métodos de descubrimiento detallado están incluidos en los paquetes de esta versión. models.list() mantiene la lista normal por defecto; las instalaciones antiguas no adquieren métodos nuevos automáticamente.

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

Conversaciones de texto

Python, Node y MCP pueden llamar a modelos de texto. El agente puede conservar su modelo principal y usar RouterShift cuando lo necesite. Los permisos y cargos siguen en la misma 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)

Solicitudes Omni por HTTP

El ejemplo envía audio WAV y solicita texto y audio mediante transmisión HTTP. Elija una ruta compatible con OpenAI ya validada, con modo stream y voz admitidos por el modelo. Los modelos que solo admiten SSE requieren stream:true; routershift_chat también acepta esta opción. El SDK conserva bloques de contenido, audio, modalidades, llamadas a herramientas y respuestas de audio. HTTP Omni no ofrece WebSocket Realtime ni conversión arbitraria entre protocolos de proveedores.

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

Generación de voz

audio.speech llama a /v1/audio/speech. Python devuelve bytes de audio; Node devuelve bytes en data y el contentType real. Elija una voz y un formato admitidos. El audio no se guarda automáticamente en archivos locales.

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

Transcripción de audio

audio.transcribe envía el archivo de audio seleccionado explícitamente mediante multipart a /v1/audio/transcriptions. Conserve su extensión real. El ejemplo solicita JSON y lee text; los idiomas y formatos admitidos dependen de la ruta.

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)

Transcribir una URL de audio HTTPS

Use audio.transcribe_url en Python, audio.transcribeURL en Node.js o envíe JSON a /v1/transcriptions con file_url. El SDK valida la URL HTTPS y no descarga la grabación localmente. Las pestañas Go y Java usan sus clientes HTTP estándar; RouterShift no afirma ofrecer SDK propios para Go o 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)

Generar imágenes y consultar tareas de imagen

Use images.generate con un modelo habilitado para generar imágenes. Para modelos con imágenes asíncronas, añada async_=True en Python o async: true en Node.js y consulte el id devuelto con images.retrieve. La respuesta final contiene data con las URL de las imágenes; una respuesta pendiente contiene id y 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))

Enviar un vídeo y consultar su estado

videos.create envía una tarea de vídeo y devuelve task_id. Guárdelo antes de consultar videos.retrieve; una tarea pendiente puede no tener todavía video_url. Ambos SDK ofrecen videos.poll para esperar con un límite de tiempo. La ruta de la API es /v1/video/generations, con video en singular.

Las rutas nativas verificadas de Seedance y Wan 3.0 admiten generate_audio: omítalo para conservar el valor del proveedor, false para quitar el audio y true para incluirlo. Wan lo convierte en parameters.audio y actualmente incluye sonido por defecto. Activarlo o desactivarlo usa la misma tarifa de vídeo Wan, sin cargo adicional de audio. Otras rutas pueden no admitirlo; los valores explícitos no se descartan silenciosamente.

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)

Añadir herramientas de modelos al agente

Añada herramientas al agente mediante MCP o use el SDK Python/Node en su aplicación: son opciones de acceso paralelas. Siga estos cuatro pasos de stdio local y no incluya credenciales en configuraciones compartidas ni en el control de versiones.

1. 1. Crear un directorio dedicado e instalar MCP

   Use Node 20 o posterior. Esta instalación exclusiva para MCP añade las dos dependencias pares del protocolo; la instalación normal del SDK Node no las necesita.

   shell

   Copiar

   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. Obtener la ruta absoluta del servidor

   Ejecute el comando en el directorio nuevo. Imprime una ruta absoluta escapada para JSON que puede pegar en el array args de la configuración.

   Node.js

   Copiar

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

3. 3. Configurar el cliente stdio local

   Sustituya la ruta de ejemplo, defina la clave API solo en el entorno local y conserve el origen de API de confianza sin /v1, credenciales, consulta ni fragmento. La pestaña Codex usa la sintaxis documentada de stdio y env_vars.

   mcpServers JSONCodex TOML

   Copiar

   {
     "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. Reiniciar el conector y verificar diez herramientas

   Reinicie o recargue el cliente MCP, confirme que aparecen las diez herramientas y ejecute primero routershift_list_models, que es de solo lectura. Invoque una herramienta de modelo facturable solo cuando quiera enviar esa operación.

Hay diez herramientas: 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. Elija primero un modelo compatible con la operación. Consulte tareas de imagen o vídeo con routershift_get_task, indicando kind (image o video) y task_id. Consulte el comprobante de una solicitud con routershift_get_request y request_id, en modo de solo lectura; esto no envía ni activa una operación de pago. En 0.3.7, details:true consulta modelos y contratos detallados. routershift_estimate_chat solo consulta un límite superior finito de admisión: sin llamada al proveedor, reserva ni ejecución automática; funds_verified=false. La cotización no es la factura final ni una autorización de ejecución.

routershift_chat acepta referencias HTTPS de imágenes y vídeo; audio_file lee una ruta absoluta WAV/MP3 seleccionada explícitamente, hasta 16 MiB. routershift_transcribe lee un archivo local seleccionado mediante file_path; routershift_transcribe_url pasa un file_url HTTPS sin descargarlo. La voz y el audio Omni se devuelven integrados. routershift_generate_image acepta response_format url o b64_json; si la salida b64_json es un PNG, JPEG, WebP o GIF válido y de tamaño limitado, devuelve contenido image nativo de MCP sin escribir, descargar ni realojar archivos y sin copiar Base64 en JSON de texto. Los datos demasiado grandes o de formato desconocido se omiten explícitamente; no repita una solicitud de pago para recuperar una salida omitida. El adaptador no explora directorios ni guarda resultados automáticamente.

La pestaña JSON muestra la estructura mcpServers habitual; la pestaña TOML muestra la sintaxis documentada de Codex. Las ubicaciones de configuración y los permisos de subprocesos varían según el cliente. Los clientes exclusivamente remotos necesitan otro transporte compatible; estos ejemplos no afirman haberse probado en todas las interfaces de agentes.

El adaptador MCP local permite llamar a las API de texto, multimodalidad, audio y tareas de RouterShift. La pasarela /v1/mcp existente da acceso a herramientas externas configuradas. Su configuración HTTP/SSE no sustituye la configuración local de herramientas de modelos mostrada aquí.