API compatible OpenAI

De quoi s’agit-il

L’API compatible OpenAI permet à un outil qui parle le format chat completions d’OpenAI d’utiliser les modèles de chat de ToRun, payés depuis votre compte ToRun. Un agent de code comme opencode peut utiliser ToRun comme fournisseur de modèles, à côté des outils MCP de ToRun.

Adresse et connexion

Utilisez la même clé développeur que pour le serveur MCP : voir Clés développeur. Une clé créée avant l’ajout de l’API compatible OpenAI reçoit la réponse 403 insufficient_scope. Les autorisations d’une clé ne changent jamais : créez donc une nouvelle clé.

L’API a deux points de terminaison, GET /v1/models et POST /v1/chat/completions. Tout autre chemin sous /v1 répond 404 not_found.

Modèles

GET /v1/models liste d’abord torun/auto, puis chaque modèle de texte que votre forfait peut utiliser, par son identifiant de modèle. Chaque modèle indique :

• la quantité de texte qu’il peut lire (context_length) et la longueur de réponse qu’il peut écrire (max_completion_tokens),
• s’il peut appeler des outils (supports_tools) et lire des images (supports_vision),
• son prix en Runs par million de tokens (pricing : input et output).

torun/auto laisse ToRun choisir un modèle pour chaque requête : un modèle qui lit les images quand la requête contient une image, et un modèle qui appelle des outils quand elle envoie tools.

Chat completions

POST /v1/chat/completions accepte :

• messages, avec les rôles system, developer (traité comme system), user, assistant et tool,
• tools et tool_choice (auto, none, required ou une fonction nommée) : les outils propres à votre outil lui reviennent sous forme d’appels d’outils, et ToRun ne les exécute jamais,
• response_format avec json_object. json_schema est accepté et la réponse est en JSON, mais le schéma lui-même n’est pas imposé,
• temperature (de 0 à 2), top_p (de 0 à 1), max_completion_tokens ou max_tokens, stop (jusqu’à 4 séquences), seed et reasoning_effort,
• stream et stream_options.include_usage.

n supérieur à 1, logprobs, top_logprobs, l’audio et toute sortie autre que du texte sont refusés avec 400 unsupported_parameter plutôt qu’ignorés.

Images

Envoyez une image en ligne, sous la forme data:image/...;base64,... dans une partie image_url, jusqu’à 20 Mo par requête. Une image envoyée sous forme de lien est refusée avec 400 image_url_not_supported : ToRun ne la récupère pas. Les images font l’objet d’un contrôle de sécurité, comme dans l’application.

Streaming

Avec "stream": true, la réponse arrive sous forme d’événements envoyés par le serveur au format chat.completion.chunk :

• Le premier fragment porte le rôle assistant, et les appels d’outils sont diffusés avec leur index.
• Tant qu’il n’y a rien à envoyer, une ligne de commentaire : keepalive arrive toutes les 15 secondes ; les analyseurs SSE l’ignorent.
• data: [DONE] termine un flux qui a réussi.
• Avec stream_options.include_usage, le dernier fragment a un choices vide et porte usage.
• Une erreur survenue après le début du flux arrive sous la forme d’un seul événement data: {"error": ...}, sans [DONE].

Un appel sans streaming est arrêté au bout de 110 secondes avec 504 timeout. Envoyez les requêtes longues avec "stream": true.

Utilisation

usage contient prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens et completion_tokens_details.reasoning_tokens, ainsi que torun_credits : ce que l’appel a coûté, en Runs.

L’utiliser dans opencode

La configuration opencode de la page Développeurs ajoute ToRun comme fournisseur de modèles à côté du serveur MCP :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "torun": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ToRun",
      "options": { "baseURL": "https://mcp.torun.ai/v1", "apiKey": "{env:TORUN_API_KEY}" },
      "models": { "torun/auto": { "name": "ToRun Auto" } }
    }
  }
}

Tout autre outil qui parle l’API de chat d’OpenAI fonctionne de la même façon. L’onglet API OpenAI de la page montre cet appel :

curl https://mcp.torun.ai/v1/chat/completions \
  -H "Authorization: Bearer $TORUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "torun/auto", "messages": [{"role": "user", "content": "Hello"}]}'

Comment les appels sont payés

Les appels API coûtent les mêmes Runs que le même usage dans l’application. Seuls des fonds payants les paient : d’abord l’allocation de votre forfait payant, puis votre portefeuille si vous l’avez autorisé pour la clé. L’allocation gratuite ne paie jamais les appels API. Les limites mensuelle et quotidienne de la clé s’appliquent, et les réponses font l’objet d’un contrôle de sécurité comme les réponses du chat.

Limites

Chaque clé peut envoyer 60 requêtes par minute à cette API et exécuter 4 completions en même temps. Au-delà, l’API répond 429 rate_limit_exceeded avec un en-tête Retry-After.

Erreurs

Chaque erreur a la forme {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. Le message est dans la langue demandée par l’en-tête Accept-Language de la requête.

Une requête qui ne peut pas être payée répond 402, et non 429, pour qu’un client ne continue pas à la relancer.