OpenAI-kompatibilis API

Mi ez

Az OpenAI-kompatibilis API lehetővé teszi, hogy az OpenAI chat completions formátumát ismerő eszközök a ToRun csevegőmodelljeit használják, a ToRun-fiókjából fizetve. Egy kódoló ügynök, például az opencode, a ToRun MCP-eszközei mellett modellszolgáltatóként is használhatja a ToRun-t.

Cím és bejelentkezés

Ugyanazt a fejlesztői kulcsot használja, mint az MCP-szerverhez: lásd Fejlesztői kulcsok. Az OpenAI-kompatibilis API megjelenése előtt létrehozott kulcs 403 insufficient_scope választ kap. A kulcs jogosultságai soha nem változnak, ezért hozzon létre új kulcsot.

Az API-nak két végpontja van: GET /v1/models és POST /v1/chat/completions. Bármely más útvonal a /v1 alatt 404 not_found választ ad.

Modellek

A GET /v1/models először a torun/auto modellt sorolja fel, majd minden szöveges modellt, amelyet a csomagja használhat, a modellazonosítójuk szerint. Minden modellnél szerepel:

• mennyi szöveget tud elolvasni (context_length), és milyen hosszú választ tud írni (max_completion_tokens),
• tud-e eszközöket hívni (supports_tools) és képeket olvasni (supports_vision),
• az ára Runs egységben millió tokenenként (pricing: input és output).

A torun/auto segítségével a ToRun minden kéréshez modellt választ: olyat, amely képeket olvas, ha a kérésben kép van, és olyat, amely eszközöket hív, ha a kérés tools mezőt küld.

Chat completions

A POST /v1/chat/completions a következőket fogadja:

• messages, a system, developer (system-ként kezelve), user, assistant és tool szerepekkel,
• tools és tool_choice (auto, none, required vagy egy megnevezett függvény): az Ön eszközének saját eszközei eszközhívásként térnek vissza hozzá, és a ToRun soha nem futtatja őket,
• response_format json_object értékkel. A json_schema elfogadott, és a válasz JSON formátumú, de magát a sémát nem kényszerítjük ki,
• temperature (0–2), top_p (0–1), max_completion_tokens vagy max_tokens, stop (legfeljebb 4 sorozat), seed és reasoning_effort,
• stream és stream_options.include_usage.

Az 1-nél nagyobb n, a logprobs, a top_logprobs, a hang és minden nem szöveges kimenet 400 unsupported_parameter hibával elutasításra kerül, nem pedig figyelmen kívül hagyásra.

Képek

A képet beágyazva küldje, data:image/...;base64,... formában egy image_url részben, kérésenként legfeljebb 20 MB-ig. A linkként küldött képet 400 image_url_not_supported hibával elutasítjuk: a ToRun nem tölti le. A képek biztonsági ellenőrzésen mennek át, mint az alkalmazásban.

Streamelés

"stream": true esetén a válasz server-sent events formájában, chat.completion.chunk alakban érkezik:

• Az első darab az assistant szerepet hordozza, az eszközhívások pedig a saját index értékükkel streamelődnek.
• Amíg nincs mit küldeni, 15 másodpercenként egy : keepalive megjegyzéssor érkezik; az SSE-elemzők átugorják.
• A data: [DONE] zárja le a sikeres streamet.
• stream_options.include_usage esetén az utolsó darab choices mezője üres, és usage mezőt tartalmaz.
• A stream kezdete utáni hiba egyetlen data: {"error": ...} eseményként érkezik, [DONE] nélkül.

A streamelés nélküli hívás 110 másodperc után 504 timeout hibával leáll. A hosszú kéréseket "stream": true beállítással küldje.

Használat

A usage tartalmazza a prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens és completion_tokens_details.reasoning_tokens értékeket, valamint a torun_credits mezőt: azt, hogy a hívás hány Runs-ba került.

Használat az opencode-ban

A Fejlesztőknek oldalon található opencode-konfiguráció az MCP-szerver mellé modellszolgáltatóként is felveszi a ToRun-t:

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

Bármely más eszköz, amely ismeri az OpenAI csevegő API-ját, ugyanígy működik. Az oldal OpenAI API lapja ezt a hívást mutatja:

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

Hogyan fizetik a hívásokat

Az API-hívások ugyanannyi Runs-ba kerülnek, mint ugyanaz a használat az alkalmazásban. Csak fizetett összegekből fizethetők: először a fizetős csomagja keretéből, majd a tárcájából, ha ezt engedélyezte a kulcson. Az ingyenes keret soha nem fizeti az API-hívásokat. A kulcs havi és napi korlátja érvényes, a válaszok pedig ugyanúgy biztonsági ellenőrzésen mennek át, mint a csevegési válaszok.

Korlátok

Minden kulcs percenként 60 kérést küldhet ennek az API-nak, és egyszerre 4 completions műveletet futtathat. Ezen felül az API 429 rate_limit_exceeded választ ad Retry-After fejléccel.

Hibák

Minden hiba {"error": {"message": ..., "type": ..., "param": ..., "code": ...}} alakú. A message azon a nyelven érkezik, amelyet a kérés Accept-Language fejléce kér.

A ki nem fizethető kérés 402-es, nem 429-es választ kap, hogy az ügyfél ne próbálkozzon vele újra és újra.