API kompatibilné s OpenAI

Čo to je

API kompatibilné s OpenAI umožňuje nástroju, ktorý ovláda formát chat completions od OpenAI, používať chatovacie modely ToRun s platbou z vášho účtu ToRun. Programovací agent ako opencode môže používať ToRun ako svojho poskytovateľa modelov vedľa nástrojov MCP od ToRun.

Adresa a prihlásenie

Použite rovnaký vývojársky kľúč ako pre MCP server: pozrite Vývojárske kľúče. Kľúč vytvorený pred pridaním API kompatibilného s OpenAI dostane odpoveď 403 insufficient_scope. Oprávnenia kľúča sa nikdy nemenia, takže vytvorte nový kľúč.

API má dva koncové body, GET /v1/models a POST /v1/chat/completions. Akákoľvek iná cesta pod /v1 odpovie 404 not_found.

Modely

GET /v1/models uvádza najprv torun/auto a potom každý textový model, ktorý môže váš plán používať, podľa jeho ID. Pri každom modeli je uvedené:

• koľko textu dokáže prečítať (context_length) a ako dlhú odpoveď dokáže napísať (max_completion_tokens),
• či vie volať nástroje (supports_tools) a čítať obrázky (supports_vision),
• jeho cena v Runs za milión tokenov (pricing: input a output).

torun/auto nechá ToRun vybrať model pre každú požiadavku: taký, ktorý číta obrázky, keď požiadavka obsahuje obrázok, a taký, ktorý volá nástroje, keď posiela tools.

Chat completions

POST /v1/chat/completions prijíma:

• messages s rolami system, developer (spracúva sa ako system), user, assistant a tool,
• tools a tool_choice (auto, none, required alebo jedna pomenovaná funkcia): vlastné nástroje vášho nástroja sa mu vracajú ako volania nástrojov a ToRun ich nikdy nespúšťa,
• response_format s json_object. json_schema je prijatý a odpoveď príde v JSON, ale samotná schéma sa nevynucuje,
• temperature (0 až 2), top_p (0 až 1), max_completion_tokens alebo max_tokens, stop (až 4 sekvencie), seed a reasoning_effort,
• stream a stream_options.include_usage.

n väčšie ako 1, logprobs, top_logprobs, zvuk a akýkoľvek iný výstup než text sú odmietnuté s 400 unsupported_parameter, nie ignorované.

Obrázky

Obrázok posielajte vložený, ako data:image/...;base64,... v časti image_url, do 20 MB na požiadavku. Obrázok poslaný ako odkaz je odmietnutý s 400 image_url_not_supported: ToRun ho nesťahuje. Obrázky prechádzajú bezpečnostnou kontrolou, rovnako ako v aplikácii.

Streamovanie

S "stream": true prichádza odpoveď ako server-sent events v tvare chat.completion.chunk:

• Prvý blok nesie rolu assistant a volania nástrojov sa streamujú so svojím index.
• Keď nie je čo poslať, príde každých 15 sekúnd komentárový riadok : keepalive; parsery SSE ho preskočia.
• data: [DONE] ukončuje stream, ktorý prebehol úspešne.
• S stream_options.include_usage má posledný blok prázdne choices a nesie usage.
• Chyba po začiatku streamu príde ako jedna udalosť data: {"error": ...}, bez [DONE].

Volanie bez streamovania sa po 110 sekundách zastaví s 504 timeout. Dlhé požiadavky posielajte s "stream": true.

Využitie

usage obsahuje prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens a completion_tokens_details.reasoning_tokens a navyše torun_credits: koľko volanie stálo v Runs.

Použitie v opencode

Konfigurácia opencode na stránke Pre vývojárov pridá ToRun ako poskytovateľa modelov vedľa MCP servera:

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

Akýkoľvek iný nástroj, ktorý ovláda chatovacie API OpenAI, funguje rovnako. Karta OpenAI API na tejto stránke ukazuje toto volanie:

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

Ako sa volania platia

Volania API stoja rovnako Runs ako rovnaké použitie v aplikácii. Platia ich len platené prostriedky: najprv limit vášho plateného plánu, potom peňaženka, ak ste to pri kľúči povolili. Bezplatný limit volania API nikdy neplatí. Platia mesačné a denné limity kľúča a odpovede prechádzajú bezpečnostnou kontrolou rovnako ako odpovede v chate.

Limity

Každý kľúč môže tomuto API poslať 60 požiadaviek za minútu a spúšťať 4 completions súčasne. Nad túto hranicu API odpovie 429 rate_limit_exceeded s hlavičkou Retry-After.

Chyby

Každá chyba má tvar {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. message je v jazyku, ktorý požaduje hlavička Accept-Language požiadavky.

Požiadavka, ktorú nemožno zaplatiť, dostane odpoveď 402, nie 429, aby ju klient neopakoval stále dokola.