API compatibile con OpenAI

Che cos'è

L'API compatibile con OpenAI permette a uno strumento che usa il formato chat completions di OpenAI di usare i modelli di chat di ToRun, pagati dal tuo account ToRun. Un agente di programmazione come opencode può usare ToRun come provider di modelli, accanto agli strumenti MCP di ToRun.

Indirizzo e accesso

Usa la stessa chiave sviluppatore del server MCP: vedi Chiavi sviluppatore. Una chiave creata prima che venisse aggiunta l'API compatibile con OpenAI riceve la risposta 403 insufficient_scope. I permessi di una chiave non cambiano mai, quindi crea una nuova chiave.

L'API ha due endpoint, GET /v1/models e POST /v1/chat/completions. Qualsiasi altro percorso sotto /v1 risponde 404 not_found.

Modelli

GET /v1/models elenca prima torun/auto, poi ogni modello di testo che il tuo piano può usare, con il suo id di modello. Ogni modello indica:

• quanto testo può leggere (context_length) e quanto può essere lunga una risposta che scrive (max_completion_tokens),
• se può chiamare strumenti (supports_tools) e leggere immagini (supports_vision),
• il suo prezzo in Runs per milione di token (pricing: input e output).

torun/auto lascia che ToRun scelga un modello per ogni richiesta: uno che legge le immagini quando la richiesta contiene un'immagine, e uno che chiama strumenti quando invia tools.

Chat completions

POST /v1/chat/completions accetta:

• messages, con i ruoli system, developer (trattato come system), user, assistant e tool,
• tools e tool_choice (auto, none, required o una funzione con nome): gli strumenti del tuo strumento gli tornano come chiamate a strumenti, e ToRun non li esegue mai,
• response_format con json_object. json_schema è accettato e la risposta è in JSON, ma lo schema in sé non viene imposto,
• temperature (da 0 a 2), top_p (da 0 a 1), max_completion_tokens o max_tokens, stop (fino a 4 sequenze), seed e reasoning_effort,
• stream e stream_options.include_usage.

n maggiore di 1, logprobs, top_logprobs, l'audio e qualsiasi output diverso dal testo vengono rifiutati con 400 unsupported_parameter invece di essere ignorati.

Immagini

Invia un'immagine inline, come data:image/...;base64,... in una parte image_url, fino a 20 MB per richiesta. Un'immagine inviata come link viene rifiutata con 400 image_url_not_supported: ToRun non la scarica. Le immagini passano un controllo di sicurezza, come nell'app.

Streaming

Con "stream": true la risposta arriva come server-sent events nel formato chat.completion.chunk:

• Il primo chunk porta il ruolo assistant, e le chiamate a strumenti vengono trasmesse con il loro index.
• Finché non c'è nulla da inviare, arriva una riga di commento : keepalive ogni 15 secondi; i parser SSE la ignorano.
• data: [DONE] chiude uno stream andato a buon fine.
• Con stream_options.include_usage, l'ultimo chunk ha choices vuoto e porta usage.
• Un errore dopo l'inizio dello stream arriva come un unico evento data: {"error": ...}, senza [DONE].

Una chiamata senza streaming viene interrotta dopo 110 secondi con 504 timeout. Invia le richieste lunghe con "stream": true.

Utilizzo

usage contiene prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens e completion_tokens_details.reasoning_tokens, più torun_credits: quanto è costata la chiamata, in Runs.

Usala in opencode

La configurazione di opencode nella pagina Sviluppatori aggiunge ToRun come provider di modelli accanto al server 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" } }
    }
  }
}

Qualsiasi altro strumento che usa l'API di chat di OpenAI funziona allo stesso modo. La scheda API OpenAI della pagina mostra questa chiamata:

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

Come vengono pagate le chiamate

Le chiamate API costano gli stessi Runs dello stesso uso nell'app. Le pagano solo fondi a pagamento: prima la quota del tuo piano a pagamento, poi il tuo portafoglio se lo hai consentito sulla chiave. La quota gratuita non paga mai le chiamate API. Valgono i limiti mensile e giornaliero della chiave, e le risposte passano un controllo di sicurezza come le risposte della chat.

Limiti

Ogni chiave può fare 60 richieste al minuto a questa API ed eseguire 4 completion contemporaneamente. Oltre questa soglia, l'API risponde 429 rate_limit_exceeded con un'intestazione Retry-After.

Errori

Ogni errore ha la forma {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. Il message è nella lingua richiesta dall'intestazione Accept-Language della richiesta.

Una richiesta che non può essere pagata risponde 402, non 429, così un client non continua a riprovarla.