Documentation API

Téléchargements Python 0.3.7 et Node 0.3.7

Les téléchargements à version fixe de cette page correspondent à Python 0.3.7 et Node 0.3.7 et incluent la découverte détaillée des modèles. Python 3.9 ou ultérieur est requis ; Node.js et MCP local exigent Node 20 ou ultérieur. Ces archives ne signifient pas une publication sur npm ou PyPI. Le SDK Node ordinaire ne nécessite pas les dépendances MCP facultatives.

Aucun code source client ni identifiant fournisseur ne sont nécessaires. Indiquez langage/environnement et version du SDK, model_code + operation + mode, paramètres anonymisés, limites des médias et expiration des URL, reprise, budget par devise et concurrence. REST est le contrat d’exécution ; les SDK sont des clients légers facultatifs et MCP local une entrée stdio pour agents. Le SDK propre utilise une origine sans /v1. Un SDK fournisseur peut exiger une adaptation des champs et répétitions ; changer seulement la clé ou l’URL ne garantit pas la compatibilité multimodale. Alignez exemples anonymisés de requête/réponse et résultats attendus. Testez d’abord des réponses synthétiques 200/202, GET en attente, SSE incomplet, envoi inconnu et livraison répétée ; l’acceptation payante exige une autorisation distincte et un budget explicite.

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

Lister les modèles visibles par votre clé API

Exécutez d’abord cette requête en lecture seule et copiez un code de modèle exact dans les exemples ci-dessous. La liste indique ce que la clé peut voir ; elle ne prouve pas que chaque opération ou mode est activé pour ce modèle.

Utilisez la même clé d’exécution pour GET /v1/models?details=1 : aucune tâche, réserve de fonds ou invocation fournisseur ; authentification, journaux et limites restent applicables. Vérifiez routes/modes de details.operations, constraints.status et import_contract.status/reason. Conservez dimensions, conditions, devise, précision, sélecteurs, heure d’observation et semantic_sha256. Un prix de référence n’est pas un contrat exécutable. Des limites absentes/inconnues ne signifient pas des entrées illimitées ; available ne garantit pas les fonds. Ce n’est ni un Schema d’entrée complet ni une projection universelle des contrats hors tokens. models.list() reste la liste ordinaire par défaut ; demandez explicitement les détails avec les méthodes incluses dans le SDK ou REST. Pour constraints, available décrit le sous-ensemble validé de l’opération ; unsupported exige sa documentation spécifique.

Distinguez details.constraints.operations[].scope : reviewed_subset désigne un sous-ensemble validé de l’opération ; finite_admission_opt_in concerne seulement les requêtes à limite finie explicitement activée, pas tout chat ordinaire. parameters n’est pas un Schema d’entrée complet. Si details.admission existe, vérifiez status, profile, /details/admission/required_headers et les limites déclarées d’entrée/sortie ; les modèles inconnus restent unavailable. La découverte n’accorde ni fonds ni plafond tarifaire universel.

Node 0.3.7 inclut listDetails() et l’option details=true de models.list ; Python 0.3.7 inclut models.list(details=True) et list_details(). Ces méthodes de découverte détaillée font partie des paquets de cette version. models.list() conserve la liste ordinaire par défaut ; les anciennes installations ne reçoivent pas automatiquement les nouvelles méthodes.

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

Conversations textuelles

Python, Node et MCP peuvent appeler des modèles de texte. L’agent peut conserver son modèle principal et utiliser RouterShift selon ses besoins. Les autorisations et les frais restent dans la même 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)

Requêtes Omni par HTTP

Cet exemple envoie du son WAV et demande du texte et du son par flux HTTP. Choisissez une route compatible OpenAI validée, avec un mode stream et une voix pris en charge par le modèle. Les modèles limités à SSE exigent stream:true ; routershift_chat accepte aussi cette option. Le SDK préserve les blocs de contenu, l’audio, les modalités, les appels d’outils et les réponses audio. HTTP Omni ne fournit ni WebSocket Realtime ni conversion arbitraire entre protocoles de fournisseurs.

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

Synthèse vocale

audio.speech appelle /v1/audio/speech. Python renvoie les octets audio ; Node renvoie les octets data et le contentType réel. Choisissez une voix et un format pris en charge. L’audio renvoyé n’est pas enregistré automatiquement dans un fichier local.

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

Transcription audio

audio.transcribe envoie le fichier audio explicitement choisi en multipart à /v1/audio/transcriptions. Conservez son extension réelle. L’exemple demande JSON et lit text ; les langues et formats dépendent de la 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)

Transcrire une URL audio HTTPS

Utilisez audio.transcribe_url en Python, audio.transcribeURL en Node.js ou envoyez du JSON à /v1/transcriptions avec file_url. Le SDK valide l’URL HTTPS sans télécharger l’enregistrement localement. Les onglets Go et Java emploient leurs clients HTTP standard ; RouterShift ne prétend pas fournir de SDK Go ou Java propriétaire.

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)

Générer des images et consulter les tâches

Utilisez images.generate avec un modèle activé pour la génération d’images. Pour les modèles prenant en charge les images asynchrones, ajoutez async_=True en Python ou async: true en Node.js, puis consultez l’id renvoyé avec images.retrieve. La réponse finale contient data et les URL des images ; une réponse en attente contient id et 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))

Soumettre une vidéo et consulter son état

videos.create soumet une tâche vidéo et renvoie task_id. Enregistrez-le avant d’appeler videos.retrieve ; une tâche en attente peut ne pas encore avoir de video_url. Les deux SDK proposent videos.poll pour une attente limitée. Le chemin de l’API est /v1/video/generations, avec video au singulier.

Les routes natives vérifiées Seedance et Wan 3.0 acceptent generate_audio : omettez-le pour garder le choix du fournisseur, false pour supprimer la piste audio, true pour l’inclure. Wan le convertit en parameters.audio et active actuellement le son par défaut. Le tarif vidéo Wan reste identique avec ou sans son, sans supplément audio. Les autres routes peuvent refuser ce champ ; une valeur explicite ne doit jamais être supprimée silencieusement.

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)

Ajouter des outils de modèles à un agent

Ajoutez des outils à un agent via MCP ou utilisez le SDK Python/Node dans votre application : ces accès sont proposés en parallèle. Suivez ces quatre étapes stdio locales et ne placez pas d’identifiants dans une configuration partagée ou un dépôt de code.

1. 1. Créer un répertoire dédié et installer MCP

   Utilisez Node 20 ou ultérieur. Cette installation réservée à MCP ajoute les deux dépendances homologues du protocole ; une installation habituelle du SDK Node n’en a pas besoin.

   shell

   Copier

   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. Résoudre le chemin absolu du serveur

   Exécutez cette commande dans le nouveau répertoire. Elle affiche un chemin absolu échappé pour JSON que vous pouvez coller dans le tableau args de la configuration.

   Node.js

   Copier

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

3. 3. Configurer le client stdio local

   Remplacez le chemin d’exemple, définissez la clé API uniquement dans votre environnement local et conservez l’origine API approuvée sans /v1, identifiants, requête ni fragment. L’onglet Codex utilise sa syntaxe stdio et env_vars documentée.

   mcpServers JSONCodex TOML

   Copier

   {
     "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. Redémarrer le connecteur et vérifier dix outils

   Redémarrez ou rechargez le client MCP, confirmez la présence des dix outils, puis appelez d’abord routershift_list_models en lecture seule. N’appelez un outil de modèle facturé que lorsque vous souhaitez soumettre cette opération.

Dix outils sont proposés : 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. Choisissez d’abord un modèle adapté à l’opération. Consultez les tâches d’image ou de vidéo avec routershift_get_task, en précisant kind (image ou video) et task_id. Consultez le reçu d’une requête avec routershift_get_request et request_id, en lecture seule ; cela ne soumet ni n’active aucune opération payante. Dans 0.3.7, details:true lit les modèles et contrats détaillés. routershift_estimate_chat observe uniquement une borne supérieure finie d’admission : aucun appel fournisseur, aucune réservation ni exécution automatique ; funds_verified=false. Un devis n’est ni une facture finale ni une autorisation d’exécution.

routershift_chat accepte des références HTTPS d’images et de vidéos ; audio_file lit un chemin absolu WAV/MP3 explicitement choisi, de 16 MiB au maximum. routershift_transcribe lit un fichier local choisi via file_path ; routershift_transcribe_url transmet un file_url HTTPS sans le télécharger. La synthèse vocale et l’audio Omni sont renvoyés de façon intégrée. routershift_generate_image accepte response_format url ou b64_json ; pour une sortie b64_json PNG, JPEG, WebP ou GIF valide et de taille limitée, il renvoie du contenu image MCP natif sans écrire, télécharger ni réhéberger de fichier, et sans copier le Base64 dans du JSON texte. Les données trop volumineuses ou de format inconnu sont explicitement omises ; ne renvoyez pas une requête payante pour récupérer une sortie omise. L’adaptateur ne parcourt pas les répertoires et n’enregistre pas automatiquement les résultats.

L’onglet JSON présente la structure mcpServers courante ; l’onglet TOML présente la syntaxe Codex documentée. Les emplacements de configuration et les autorisations de sous-processus varient selon le client. Les clients exclusivement distants nécessitent un autre transport pris en charge ; ces exemples ne prétendent pas avoir été testés dans toutes les interfaces d’agent.

L’adaptateur MCP local permet d’appeler les API RouterShift de texte, multimodalité, audio et tâches. La passerelle /v1/mcp existante donne accès aux outils externes configurés. Sa configuration HTTP/SSE ne remplace pas la configuration locale des outils de modèles présentée ici.