API kompatibilan s OpenAI-jem

Što je to

API kompatibilan s OpenAI-jem omogućuje alatu koji podržava OpenAI format chat completions da koristi ToRun modele za razgovor, uz plaćanje s vašeg ToRun računa. Agent za programiranje poput opencode može koristiti ToRun kao svojeg pružatelja modela, uz ToRun MCP alate.

Adresa i prijava

Koristite isti programerski ključ kao za MCP poslužitelj: pogledajte Programerski ključevi. Ključ izrađen prije dodavanja API-ja kompatibilnog s OpenAI-jem dobiva odgovor 403 insufficient_scope. Dopuštenja ključa nikad se ne mijenjaju, pa izradite novi ključ.

API ima dvije krajnje točke, GET /v1/models i POST /v1/chat/completions. Svaka druga putanja pod /v1 odgovara 404 not_found.

Modeli

GET /v1/models najprije navodi torun/auto, a zatim svaki tekstni model koji vaš plan može koristiti, prema ID-ju modela. Za svaki model navedeno je:

• koliko teksta može pročitati (context_length) i koliko dug odgovor može napisati (max_completion_tokens),
• može li pozivati alate (supports_tools) i čitati slike (supports_vision),
• njegova cijena u Runs po milijunu tokena (pricing: input i output).

torun/auto omogućuje ToRun da za svaki zahtjev odabere model: onaj koji čita slike kad zahtjev sadrži sliku i onaj koji poziva alate kad šalje tools.

Chat completions

POST /v1/chat/completions prihvaća:

• messages, s ulogama system, developer (obrađuje se kao system), user, assistant i tool,
• tools i tool_choice (auto, none, required ili jedna imenovana funkcija): vlastiti alati vašeg alata vraćaju mu se kao pozivi alata, a ToRun ih nikad ne pokreće,
• response_format s json_object. json_schema se prihvaća i odgovor stiže u JSON-u, ali se sama shema ne nameće,
• temperature (od 0 do 2), top_p (od 0 do 1), max_completion_tokens ili max_tokens, stop (do 4 niza), seed i reasoning_effort,
• stream i stream_options.include_usage.

n veći od 1, logprobs, top_logprobs, audio i svaki izlaz osim teksta odbijaju se s 400 unsupported_parameter umjesto da se zanemare.

Slike

Šaljite sliku ugrađenu, kao data:image/...;base64,... u dijelu image_url, do 20 MB po zahtjevu. Slika poslana kao poveznica odbija se s 400 image_url_not_supported: ToRun je ne dohvaća. Slike prolaze sigurnosnu provjeru, kao u aplikaciji.

Strujanje

Uz "stream": true odgovor stiže kao server-sent events u obliku chat.completion.chunk:

• Prvi dio nosi ulogu assistant, a pozivi alata struje sa svojim index.
• Dok nema ničega za slanje, svakih 15 sekundi stiže redak komentara : keepalive; SSE parseri ga preskaču.
• data: [DONE] završava uspješan tok.
• Uz stream_options.include_usage posljednji dio ima prazan choices i nosi usage.
• Pogreška nakon početka toka stiže kao jedan događaj data: {"error": ...}, bez [DONE].

Poziv bez strujanja zaustavlja se nakon 110 sekundi s 504 timeout. Duge zahtjeve šaljite s "stream": true.

Potrošnja

usage sadrži prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens i completion_tokens_details.reasoning_tokens te torun_credits: koliko je poziv koštao, u Runs.

Upotreba u opencode

Konfiguracija opencode na stranici Za programere dodaje ToRun kao pružatelja modela uz MCP poslužitelj:

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

Svaki drugi alat koji podržava OpenAI chat API radi na isti način. Kartica OpenAI API na toj stranici prikazuje ovaj poziv:

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

Kako se pozivi plaćaju

API pozivi koštaju isto Runs kao ista upotreba u aplikaciji. Plaćaju ih samo plaćena sredstva: najprije kvota vašeg plaćenog plana, a zatim novčanik ako ste to dopustili na ključu. Besplatna kvota nikad ne plaća API pozive. Primjenjuju se mjesečno i dnevno ograničenje ključa, a odgovori prolaze sigurnosnu provjeru kao i odgovori u razgovoru.

Ograničenja

Svaki ključ može ovom API-ju poslati 60 zahtjeva u minuti i istodobno izvoditi 4 completions. Iznad toga API odgovara 429 rate_limit_exceeded sa zaglavljem Retry-After.

Pogreške

Svaka pogreška ima oblik {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. message je na jeziku koji traži zaglavlje Accept-Language zahtjeva.

Zahtjev koji se ne može platiti dobiva odgovor 402, a ne 429, kako ga klijent ne bi stalno ponavljao.