API kompatibilní s OpenAI

Co to je

API kompatibilní s OpenAI umožňuje nástroji, který umí formát chat completions od OpenAI, používat chatovací modely ToRun s platbou z vašeho účtu ToRun. Programovací agent jako opencode může používat ToRun jako svého poskytovatele modelů vedle nástrojů MCP od ToRun.

Adresa a přihlášení

Použijte stejný vývojářský klíč jako pro MCP server: viz Vývojářské klíče. Klíč vytvořený před přidáním API kompatibilního s OpenAI dostane odpověď 403 insufficient_scope. Oprávnění klíče se nikdy nemění, takže vytvořte nový klíč.

API má dva koncové body, GET /v1/models a POST /v1/chat/completions. Jakákoli jiná cesta pod /v1 odpoví 404 not_found.

Modely

GET /v1/models uvádí nejprve torun/auto a potom každý textový model, který může váš plán používat, podle jeho ID. U každého modelu je uvedeno:

• kolik textu dokáže přečíst (context_length) a jak dlouhou odpověď dokáže napsat (max_completion_tokens),
• zda umí volat nástroje (supports_tools) a číst obrázky (supports_vision),
• jeho cena v Runs za milion tokenů (pricing: input a output).

torun/auto nechá ToRun vybrat model pro každý požadavek: takový, který čte obrázky, když požadavek obsahuje obrázek, a takový, který volá nástroje, když posílá tools.

Chat completions

POST /v1/chat/completions přijímá:

• messages s rolemi system, developer (zpracovává se jako system), user, assistant a tool,
• tools a tool_choice (auto, none, required nebo jedna pojmenovaná funkce): vlastní nástroje vašeho nástroje se mu vracejí jako volání nástrojů a ToRun je nikdy nespouští,
• response_format s json_object. json_schema je přijat a odpověď přijde v JSON, ale samotné schéma se nevynucuje,
• temperature (0 až 2), top_p (0 až 1), max_completion_tokens nebo max_tokens, stop (až 4 sekvence), seed a reasoning_effort,
• stream a stream_options.include_usage.

n větší než 1, logprobs, top_logprobs, zvuk a jakýkoli jiný výstup než text jsou odmítnuty s 400 unsupported_parameter, nikoli ignorovány.

Obrázky

Obrázek posílejte vložený, jako data:image/...;base64,... v části image_url, do 20 MB na požadavek. Obrázek poslaný jako odkaz je odmítnut s 400 image_url_not_supported: ToRun ho nestahuje. Obrázky procházejí bezpečnostní kontrolou, stejně jako v aplikaci.

Streamování

S "stream": true přichází odpověď jako server-sent events ve tvaru chat.completion.chunk:

• První blok nese roli assistant a volání nástrojů se streamují se svým index.
• Když není co poslat, přijde každých 15 sekund komentářový řádek : keepalive; parsery SSE ho přeskočí.
• data: [DONE] ukončuje stream, který proběhl úspěšně.
• S stream_options.include_usage má poslední blok prázdné choices a nese usage.
• Chyba po začátku streamu přijde jako jedna událost data: {"error": ...}, bez [DONE].

Volání bez streamování se po 110 sekundách zastaví s 504 timeout. Dlouhé požadavky posílejte s "stream": true.

Využití

usage obsahuje prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens a completion_tokens_details.reasoning_tokens a navíc torun_credits: kolik volání stálo v Runs.

Použití v opencode

Konfigurace opencode na stránce Pro vývojáře přidá ToRun jako poskytovatele modelů vedle MCP serveru:

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

Jakýkoli jiný nástroj, který umí chatovací API OpenAI, funguje stejně. Karta OpenAI API na této stránce ukazuje toto volání:

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

Jak se volání platí

Volání API stojí stejně Runs jako stejné použití v aplikaci. Platí je jen placené prostředky: nejprve limit vašeho placeného plánu, potom peněženka, pokud jste to u klíče povolili. Bezplatný limit volání API nikdy neplatí. Platí měsíční a denní limity klíče a odpovědi procházejí bezpečnostní kontrolou stejně jako odpovědi v chatu.

Limity

Každý klíč může tomuto API poslat 60 požadavků za minutu a spouštět 4 completions současně. Nad tuto mez API odpoví 429 rate_limit_exceeded s hlavičkou Retry-After.

Chyby

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

Požadavek, který nelze zaplatit, dostane odpověď 402, ne 429, aby ho klient neopakoval pořád dokola.