API compatibil cu OpenAI

Ce este

API-ul compatibil cu OpenAI permite unui instrument care folosește formatul chat completions al OpenAI să utilizeze modelele de chat ToRun, plătite din contul dvs. ToRun. Un agent de programare precum opencode poate folosi ToRun ca furnizor de modele, alături de instrumentele MCP ToRun.

Adresă și autentificare

Folosiți aceeași cheie de dezvoltator ca pentru serverul MCP: consultați Chei de dezvoltator. O cheie creată înainte de adăugarea API-ului compatibil cu OpenAI primește răspunsul 403 insufficient_scope. Permisiunile unei chei nu se schimbă niciodată, așa că creați o cheie nouă.

API-ul are două puncte finale, GET /v1/models și POST /v1/chat/completions. Orice altă cale sub /v1 răspunde cu 404 not_found.

Modele

GET /v1/models listează mai întâi torun/auto, apoi fiecare model de text pe care îl poate folosi planul dvs., după ID-ul modelului. Pentru fiecare model se indică:

• cât text poate citi (context_length) și cât de lung poate fi răspunsul pe care îl scrie (max_completion_tokens),
• dacă poate apela instrumente (supports_tools) și citi imagini (supports_vision),
• prețul său în Runs per milion de tokeni (pricing: input și output).

torun/auto îi permite lui ToRun să aleagă un model pentru fiecare cerere: unul care citește imagini când cererea conține o imagine și unul care apelează instrumente când trimite tools.

Chat completions

POST /v1/chat/completions acceptă:

• messages, cu rolurile system, developer (tratat ca system), user, assistant și tool,
• tools și tool_choice (auto, none, required sau o funcție anume): instrumentele proprii ale instrumentului dvs. îi revin ca apeluri de instrumente, iar ToRun nu le rulează niciodată,
• response_format cu json_object. json_schema este acceptat și răspunsul vine în JSON, dar schema propriu-zisă nu este impusă,
• temperature (de la 0 la 2), top_p (de la 0 la 1), max_completion_tokens sau max_tokens, stop (până la 4 secvențe), seed și reasoning_effort,
• stream și stream_options.include_usage.

n mai mare de 1, logprobs, top_logprobs, audio și orice ieșire în afară de text sunt refuzate cu 400 unsupported_parameter, nu ignorate.

Imagini

Trimiteți imaginea inline, ca data:image/...;base64,... într-o parte image_url, până la 20 MB pe cerere. O imagine trimisă ca link este refuzată cu 400 image_url_not_supported: ToRun nu o descarcă. Imaginile trec printr-o verificare de siguranță, ca în aplicație.

Streaming

Cu "stream": true, răspunsul sosește ca server-sent events în forma chat.completion.chunk:

• Primul fragment conține rolul assistant, iar apelurile de instrumente sunt transmise cu index propriu.
• Cât timp nu există nimic de trimis, la fiecare 15 secunde sosește o linie de comentariu : keepalive; parserele SSE o sar.
• data: [DONE] încheie un flux reușit.
• Cu stream_options.include_usage, ultimul fragment are choices gol și conține usage.
• O eroare apărută după începerea fluxului sosește ca un singur eveniment data: {"error": ...}, fără [DONE].

Un apel fără streaming este oprit după 110 secunde cu 504 timeout. Trimiteți cererile lungi cu "stream": true.

Utilizare

usage conține prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens și completion_tokens_details.reasoning_tokens, plus torun_credits: cât a costat apelul, în Runs.

Folosire în opencode

Configurația opencode de pe pagina Dezvoltatori adaugă ToRun ca furnizor de modele lângă serverul 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" } }
    }
  }
}

Orice alt instrument care folosește API-ul de chat OpenAI funcționează la fel. Fila OpenAI API a paginii arată acest apel:

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

Cum se plătesc apelurile

Apelurile API costă aceleași Runs ca aceeași utilizare în aplicație. Le plătesc doar fondurile plătite: mai întâi alocarea planului dvs. plătit, apoi portofelul, dacă ați permis acest lucru pe cheie. Alocarea gratuită nu plătește niciodată apelurile API. Se aplică limitele lunare și zilnice ale cheii, iar răspunsurile trec printr-o verificare de siguranță la fel ca răspunsurile din chat.

Limite

Fiecare cheie poate trimite 60 de cereri pe minut către acest API și poate rula 4 completions în același timp. Peste acestea, API-ul răspunde cu 429 rate_limit_exceeded și antetul Retry-After.

Erori

Fiecare eroare are forma {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. message este în limba cerută de antetul Accept-Language al cererii.

O cerere care nu poate fi plătită primește răspunsul 402, nu 429, ca un client să nu o tot reîncerce.