Documentação da API

Downloads de Python 0.3.7 e Node 0.3.7

Os downloads de versão fixa desta página correspondem a Python 0.3.7 e Node 0.3.7 e incluem a descoberta detalhada de modelos. É necessário Python 3.9 ou superior; Node.js e MCP local exigem Node 20 ou superior. Os arquivos não implicam publicação no npm ou PyPI. O SDK Node comum não precisa das dependências MCP opcionais.

Não são necessários código-fonte do cliente nem credenciais do fornecedor. Informe linguagem/ambiente e versão do SDK, model_code + operation + mode, parâmetros anonimizados, limites de mídia e validade de URLs, recuperação, orçamento por moeda e concorrência. REST é o contrato de execução; SDKs são clientes leves opcionais e MCP local é uma entrada stdio para agentes. O SDK próprio usa uma origem sem /v1. SDKs de fornecedores podem exigir ajustes de campos e tentativas; mudar apenas a chave ou URL base não garante compatibilidade multimodal. Alinhe amostras anônimas de solicitação/resposta e resultados esperados. Teste primeiro respostas sintéticas 200/202, GET pendente, SSE incompleto, envio desconhecido e entrega duplicada; a aceitação paga exige autorização separada e orçamento explícito.

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

Listar modelos visíveis para sua chave de API

Execute primeiro esta solicitação somente leitura e copie um código exato de modelo nos exemplos abaixo. A lista mostra o que a chave pode ver; não comprova que cada operação ou modo esteja habilitado para o modelo.

Use a mesma chave de execução em GET /v1/models?details=1: não cria tarefas, reserva fundos nem chama fornecedores; autenticação, registros e limites continuam válidos. Confira rotas/modos de details.operations, constraints.status e import_contract.status/reason. Preserve dimensões, condições, moeda, precisão, seletores, horário de observação e semantic_sha256. Preços de referência não são contratos executáveis. Restrições ausentes/desconhecidas não significam entradas ilimitadas; available não garante fundos. Não é um Schema completo por modelo nem uma projeção universal de contratos sem tokens. models.list() continua sendo a lista comum por padrão; solicite detalhes explicitamente com os métodos incluídos no SDK ou REST. Em constraints, available descreve o subconjunto revisado da operação; unsupported exige orientação específica.

Diferencie details.constraints.operations[].scope: reviewed_subset é um subconjunto revisado da operação; finite_admission_opt_in vale apenas para solicitações com limite finito explícito, não para todo chat comum. parameters não é um Schema completo de entrada. Se houver details.admission, confira status, profile, /details/admission/required_headers e os limites declarados de entrada/saída; modelos desconhecidos permanecem unavailable. A descoberta não concede fundos nem limite universal de preço.

Node 0.3.7 inclui listDetails() e a opção details=true de models.list; Python 0.3.7 inclui models.list(details=True) e list_details(). Esses métodos de descoberta detalhada fazem parte dos pacotes desta versão. models.list() mantém a lista comum por padrão; instalações antigas não recebem novos métodos automaticamente.

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

Conversas de texto

Python, Node e MCP podem chamar modelos de texto. O agente pode manter seu modelo principal e usar o RouterShift quando necessário. Permissões e cobranças continuam na mesma 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)

Solicitações Omni por HTTP

O exemplo envia áudio WAV e solicita texto e áudio por transmissão HTTP. Escolha uma rota compatível com OpenAI já validada, com modo stream e voz aceitos pelo modelo. Modelos que aceitam apenas SSE exigem stream:true; routershift_chat também aceita essa opção. O SDK preserva blocos de conteúdo, áudio, modalidades, chamadas de ferramentas e respostas de áudio. HTTP Omni não oferece WebSocket Realtime nem conversão arbitrária entre protocolos de provedores.

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

Geração de voz

audio.speech chama /v1/audio/speech. Python retorna bytes de áudio; Node retorna bytes em data e o contentType real. Escolha uma voz e um formato aceitos pelo modelo. O áudio retornado não é salvo automaticamente em arquivos locais.

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

Transcrição de áudio

audio.transcribe envia o arquivo de áudio selecionado explicitamente como multipart para /v1/audio/transcriptions. Preserve a extensão real. O exemplo solicita JSON e lê text; idiomas e formatos aceitos dependem da rota.

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)

Transcrever uma URL de áudio HTTPS

Use audio.transcribe_url em Python, audio.transcribeURL em Node.js ou envie JSON para /v1/transcriptions com file_url. O SDK valida a URL HTTPS e não baixa a gravação localmente. As abas Go e Java usam os clientes HTTP padrão dessas linguagens; o RouterShift não declara SDK próprios para Go ou 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)

Gerar imagens e consultar tarefas de imagem

Use images.generate com um modelo habilitado para gerar imagens. Nos modelos com imagens assíncronas, adicione async_=True no Python ou async: true no Node.js e consulte o id retornado com images.retrieve. A resposta concluída contém data com as URLs das imagens; uma resposta pendente contém id e 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 um vídeo e consultar seu estado

videos.create envia uma tarefa de vídeo e retorna task_id. Salve-o antes de consultar videos.retrieve; uma tarefa pendente pode ainda não ter video_url. Ambos os SDKs oferecem videos.poll para espera com prazo limitado. O caminho da API é /v1/video/generations, com video no singular.

Rotas nativas verificadas de Seedance e Wan 3.0 aceitam generate_audio: omita para manter o padrão do fornecedor, false para remover o áudio e true para incluí-lo. Wan mapeia para parameters.audio e atualmente inclui som por padrão. Ligar ou desligar o som mantém a mesma tarifa de vídeo Wan, sem cobrança extra de áudio. Outras rotas podem não aceitar o campo; valores explícitos não são descartados 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)

Adicionar ferramentas de modelos ao agente

Adicione ferramentas ao agente via MCP ou use o SDK Python/Node no código da aplicação: são opções de acesso paralelas. Siga estas quatro etapas de stdio local e não inclua credenciais em configurações compartilhadas ou no controle de versão.

1. 1. Criar um diretório dedicado e instalar o MCP

   Use Node 20 ou superior. Esta instalação exclusiva do MCP adiciona as duas dependências pares do protocolo; uma instalação comum do SDK Node não precisa delas.

   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. Resolver a entrada absoluta do servidor

   Execute no novo diretório. O comando imprime um caminho absoluto com escape JSON para colar no array args da configuração.

   Node.js

   Copiar

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

3. 3. Configurar o cliente stdio local

   Substitua o caminho de exemplo, defina a chave da API apenas no ambiente local e mantenha a origem confiável da API sem /v1, credenciais, consulta ou fragmento. A aba Codex usa a sintaxe documentada de stdio e 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 o conector e verificar dez ferramentas

   Reinicie ou recarregue o cliente MCP, confirme que as dez ferramentas aparecem e execute primeiro routershift_list_models, que é somente leitura. Invoque uma ferramenta faturada apenas quando pretender enviar a operação.

Há dez ferramentas: 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. Escolha primeiro um modelo que aceite a operação. Consulte tarefas de imagem ou vídeo com routershift_get_task, informando kind (image ou video) e task_id. Consulte o comprovante de uma solicitação com routershift_get_request e request_id, em modo somente leitura; isso não envia nem ativa uma operação paga. Na versão 0.3.7, details:true consulta modelos e contratos detalhados. routershift_estimate_chat apenas consulta um limite superior finito de admissão: sem chamada ao fornecedor, reserva ou execução automática; funds_verified=false. A cotação não é a fatura final nem uma autorização de execução.

routershift_chat aceita referências HTTPS de imagens e vídeos; audio_file lê um caminho absoluto WAV/MP3 selecionado explicitamente, até 16 MiB. routershift_transcribe lê um arquivo local selecionado por file_path; routershift_transcribe_url repassa um file_url HTTPS sem baixá-lo. Voz e áudio Omni são retornados de forma incorporada. routershift_generate_image aceita response_format url ou b64_json; para saída b64_json válida, limitada e no formato PNG, JPEG, WebP ou GIF, retorna conteúdo image nativo do MCP sem gravar, baixar ou republicar arquivos e sem copiar Base64 para JSON de texto. Dados de imagem acima do limite ou com formato desconhecido são explicitamente omitidos; não reenvie uma solicitação paga para recuperar uma saída omitida. O adaptador não procura em diretórios nem salva resultados automaticamente.

A aba JSON mostra a estrutura comum mcpServers; a aba TOML mostra a sintaxe documentada do Codex. Locais de configuração e permissões de subprocessos variam por cliente. Clientes exclusivamente remotos precisam de outro transporte compatível; estes exemplos não afirmam testes em todas as interfaces de agentes.

O adaptador MCP local permite chamar as APIs de texto, multimodalidade, áudio e tarefas do RouterShift. O gateway /v1/mcp existente dá acesso a ferramentas externas configuradas. Sua configuração HTTP/SSE não substitui a configuração local de ferramentas de modelos apresentada aqui.