API zgodne z OpenAI

Co to jest

API zgodne z OpenAI pozwala narzędziu, które obsługuje format chat completions OpenAI, używać modeli czatu ToRun z opłatą z Twojego konta ToRun. Agent programistyczny taki jak opencode może używać ToRun jako swojego dostawcy modeli obok narzędzi MCP ToRun.

Adres i logowanie

Użyj tego samego klucza programisty co dla serwera MCP: zobacz Klucze programisty. Klucz utworzony przed dodaniem API zgodnego z OpenAI dostaje odpowiedź 403 insufficient_scope. Uprawnienia klucza nigdy się nie zmieniają, więc utwórz nowy klucz.

API ma dwa punkty końcowe: GET /v1/models i POST /v1/chat/completions. Każda inna ścieżka w /v1 odpowiada 404 not_found.

Modele

GET /v1/models podaje najpierw torun/auto, a potem każdy model tekstowy, z którego może korzystać Twój plan, według jego identyfikatora. Dla każdego modelu podano:

• ile tekstu może przeczytać (context_length) i jak długą odpowiedź może napisać (max_completion_tokens),
• czy potrafi wywoływać narzędzia (supports_tools) i czytać obrazy (supports_vision),
• jego cenę w Runs za milion tokenów (pricing: input i output).

torun/auto pozwala ToRun dobrać model do każdego żądania: taki, który czyta obrazy, gdy żądanie zawiera obraz, i taki, który wywołuje narzędzia, gdy wysyła tools.

Chat completions

POST /v1/chat/completions przyjmuje:

• messages z rolami system, developer (traktowana jak system), user, assistant i tool,
• tools i tool_choice (auto, none, required lub jedna nazwana funkcja): własne narzędzia Twojego narzędzia wracają do niego jako wywołania narzędzi, a ToRun nigdy ich nie uruchamia,
• response_format z json_object. json_schema jest przyjmowany, a odpowiedź przychodzi w JSON, ale sam schemat nie jest wymuszany,
• temperature (od 0 do 2), top_p (od 0 do 1), max_completion_tokens lub max_tokens, stop (do 4 sekwencji), seed i reasoning_effort,
• stream i stream_options.include_usage.

n większe niż 1, logprobs, top_logprobs, audio i każde wyjście inne niż tekst są odrzucane z 400 unsupported_parameter, a nie ignorowane.

Obrazy

Wysyłaj obraz osadzony, jako data:image/...;base64,... w części image_url, do 20 MB na żądanie. Obraz wysłany jako link jest odrzucany z 400 image_url_not_supported: ToRun go nie pobiera. Obrazy przechodzą kontrolę bezpieczeństwa, tak jak w aplikacji.

Strumieniowanie

Przy "stream": true odpowiedź przychodzi jako server-sent events w formacie chat.completion.chunk:

• Pierwszy fragment zawiera rolę assistant, a wywołania narzędzi są przesyłane strumieniowo ze swoim index.
• Gdy nie ma nic do wysłania, co 15 sekund przychodzi wiersz komentarza : keepalive; parsery SSE go pomijają.
• data: [DONE] kończy strumień, który się powiódł.
• Z stream_options.include_usage ostatni fragment ma puste choices i zawiera usage.
• Błąd po rozpoczęciu strumienia przychodzi jako jedno zdarzenie data: {"error": ...}, bez [DONE].

Wywołanie bez strumieniowania jest przerywane po 110 sekundach z 504 timeout. Długie żądania wysyłaj z "stream": true.

Użycie

usage zawiera prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens i completion_tokens_details.reasoning_tokens, a także torun_credits: ile wywołanie kosztowało w Runs.

Użycie w opencode

Konfiguracja opencode na stronie Dla programistów dodaje ToRun jako dostawcę modeli obok serwera 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" } }
    }
  }
}

Każde inne narzędzie, które obsługuje API czatu OpenAI, działa tak samo. Karta API OpenAI na tej stronie pokazuje takie wywołanie:

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 opłacane są wywołania

Wywołania API kosztują tyle samo Runs co takie samo użycie w aplikacji. Opłacają je tylko płatne środki: najpierw limit Twojego płatnego planu, potem portfel, jeśli zezwoliłeś na to w kluczu. Darmowy limit nigdy nie opłaca wywołań API. Obowiązują miesięczny i dzienny limit klucza, a odpowiedzi przechodzą kontrolę bezpieczeństwa tak jak odpowiedzi w czacie.

Limity

Każdy klucz może wysłać do tego API 60 żądań na minutę i wykonywać 4 completions jednocześnie. Powyżej tego API odpowiada 429 rate_limit_exceeded z nagłówkiem Retry-After.

Błędy

Każdy błąd ma postać {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. message jest w języku, o który prosi nagłówek Accept-Language żądania.

Żądanie, którego nie da się opłacić, dostaje odpowiedź 402, a nie 429, aby klient nie ponawiał go w kółko.