OpenAI-compatibele API

Wat het is

Met de OpenAI-compatibele API kan een tool die het chat-completions-formaat van OpenAI spreekt de chatmodellen van ToRun gebruiken, betaald vanuit je ToRun-account. Een coding agent zoals opencode kan ToRun zo naast de MCP-tools van ToRun ook als modelprovider gebruiken.

Adres en inloggen

Gebruik dezelfde ontwikkelaarssleutel als voor de MCP-server: zie Ontwikkelaarssleutels. Een sleutel die is gemaakt voordat de OpenAI-compatibele API werd toegevoegd, krijgt 403 insufficient_scope. De rechten van een sleutel veranderen nooit, dus maak een nieuwe sleutel.

De API heeft twee endpoints, GET /v1/models en POST /v1/chat/completions. Elk ander pad onder /v1 antwoordt met 404 not_found.

Modellen

GET /v1/models toont eerst torun/auto en daarna elk tekstmodel dat je abonnement kan gebruiken, met zijn model-id. Elk model vermeldt:

• hoeveel tekst het kan lezen (context_length) en hoe lang een antwoord kan zijn dat het schrijft (max_completion_tokens),
• of het tools kan aanroepen (supports_tools) en afbeeldingen kan lezen (supports_vision),
• zijn prijs in Runs per miljoen tokens (pricing: input en output).

Met torun/auto kiest ToRun voor elk verzoek een model: een dat afbeeldingen leest als het verzoek een afbeelding bevat, en een dat tools aanroept als het tools meestuurt.

Chat completions

POST /v1/chat/completions accepteert:

• messages, met de rollen system, developer (behandeld als system), user, assistant en tool,
• tools en tool_choice (auto, none, required of één benoemde functie): de eigen tools van je tool komen als toolaanroepen naar hem terug, en ToRun voert ze nooit uit,
• response_format met json_object. json_schema wordt geaccepteerd en als JSON beantwoord, maar het schema zelf wordt niet afgedwongen,
• temperature (0 tot 2), top_p (0 tot 1), max_completion_tokens of max_tokens, stop (tot 4 reeksen), seed en reasoning_effort,
• stream en stream_options.include_usage.

n boven 1, logprobs, top_logprobs, audio en elke uitvoer anders dan tekst worden geweigerd met 400 unsupported_parameter in plaats van genegeerd.

Afbeeldingen

Stuur een afbeelding inline mee, als data:image/...;base64,... in een image_url-deel, tot 20 MB per verzoek. Een afbeelding die als link wordt gestuurd, wordt geweigerd met 400 image_url_not_supported: ToRun haalt hem niet op. Afbeeldingen worden net als in de app gecontroleerd op veiligheid.

Streaming

Met "stream": true komt het antwoord binnen als server-sent events in de vorm chat.completion.chunk:

• De eerste chunk bevat de rol assistant, en toolaanroepen worden gestreamd met hun index.
• Zolang er niets te versturen is, komt er elke 15 seconden een commentaarregel : keepalive; SSE-parsers slaan die over.
• data: [DONE] beëindigt een geslaagde stream.
• Met stream_options.include_usage heeft de laatste chunk een lege choices en bevat hij usage.
• Een fout nadat de stream is begonnen, komt binnen als één gebeurtenis data: {"error": ...}, zonder [DONE].

Een aanroep zonder streaming wordt na 110 seconden gestopt met 504 timeout. Stuur lange verzoeken met "stream": true.

Gebruik

usage bevat prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens en completion_tokens_details.reasoning_tokens, plus torun_credits: wat de aanroep heeft gekost, in Runs.

Gebruiken in opencode

De opencode-configuratie op de pagina Ontwikkelaars voegt ToRun naast de MCP-server toe als modelprovider:

{
  "$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" } }
    }
  }
}

Elke andere tool die de chat-API van OpenAI spreekt, werkt op dezelfde manier. Het tabblad OpenAI-API van de pagina toont deze aanroep:

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"}]}'

Hoe aanroepen worden betaald

API-aanroepen kosten dezelfde Runs als hetzelfde gebruik in de app. Alleen betaald tegoed betaalt ervoor: eerst het tegoed van je betaalde abonnement, daarna je wallet als je dat voor de sleutel hebt toegestaan. Het gratis tegoed betaalt nooit voor API-aanroepen. De maandelijkse en dagelijkse limieten van de sleutel gelden, en antwoorden worden net als chatantwoorden op veiligheid gecontroleerd.

Limieten

Elke sleutel kan 60 verzoeken per minuut naar deze API sturen en 4 completions tegelijk uitvoeren. Daarboven antwoordt de API met 429 rate_limit_exceeded en een Retry-After-header.

Fouten

Elke fout heeft de vorm {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. De message is in de taal waar de Accept-Language-header van het verzoek om vraagt.

Een verzoek dat niet kan worden betaald, antwoordt met 402 en niet met 429, zodat een client het niet blijft herhalen.