OpenAI-yhteensopiva API

Mikä se on

OpenAI-yhteensopivan API:n avulla työkalu, joka tukee OpenAI:n chat completions -muotoa, voi käyttää ToRunin keskustelumalleja ToRun-tililtäsi maksettuina. Koodausagentti, kuten opencode, voi käyttää ToRunia mallintarjoajanaan ToRunin MCP-työkalujen rinnalla.

Osoite ja kirjautuminen

Käytä samaa kehittäjäavainta kuin MCP-palvelimelle: katso Kehittäjäavaimet. Avain, joka on luotu ennen OpenAI-yhteensopivan API:n lisäämistä, saa vastauksen 403 insufficient_scope. Avaimen oikeudet eivät koskaan muutu, joten luo uusi avain.

API:lla on kaksi päätepistettä, GET /v1/models ja POST /v1/chat/completions. Mikä tahansa muu polku /v1:n alla vastaa 404 not_found.

Mallit

GET /v1/models luettelee ensin mallin torun/auto ja sitten jokaisen tekstimallin, jota tilauksesi voi käyttää, mallin tunnisteen mukaan. Jokaisesta mallista kerrotaan:

• kuinka paljon tekstiä se voi lukea (context_length) ja kuinka pitkän vastauksen se voi kirjoittaa (max_completion_tokens),
• voiko se kutsua työkaluja (supports_tools) ja lukea kuvia (supports_vision),
• sen hinta Runs-yksiköinä miljoonaa tokenia kohden (pricing: input ja output).

torun/auto antaa ToRunin valita mallin jokaiselle pyynnölle: kuvia lukevan mallin, kun pyynnössä on kuva, ja työkaluja kutsuvan mallin, kun se lähettää tools-kentän.

Chat completions

POST /v1/chat/completions hyväksyy:

• messages, rooleilla system, developer (käsitellään kuin system), user, assistant ja tool,
• tools ja tool_choice (auto, none, required tai yksi nimetty funktio): työkalusi omat työkalut palaavat sille työkalukutsuina, eikä ToRun koskaan aja niitä,
• response_format arvolla json_object. json_schema hyväksytään ja vastaus tulee JSON-muodossa, mutta itse skeemaa ei pakoteta,
• temperature (0–2), top_p (0–1), max_completion_tokens tai max_tokens, stop (enintään 4 jonoa), seed ja reasoning_effort,
• stream ja stream_options.include_usage.

Arvoa 1 suurempi n, logprobs, top_logprobs, ääni ja kaikki muu tuloste kuin teksti hylätään vastauksella 400 unsupported_parameter sen sijaan, että ne ohitettaisiin.

Kuvat

Lähetä kuva upotettuna muodossa data:image/...;base64,... image_url-osassa, enintään 20 Mt pyyntöä kohden. Linkkinä lähetetty kuva hylätään vastauksella 400 image_url_not_supported: ToRun ei hae sitä. Kuvat käyvät läpi turvatarkistuksen, kuten sovelluksessa.

Suoratoisto

Kun "stream": true on käytössä, vastaus saapuu server-sent events -tapahtumina chat.completion.chunk-muodossa:

• Ensimmäinen osa sisältää roolin assistant, ja työkalukutsut suoratoistetaan oman index-arvonsa kanssa.
• Kun lähetettävää ei ole, kommenttirivi : keepalive saapuu 15 sekunnin välein; SSE-jäsentimet ohittavat sen.
• data: [DONE] päättää onnistuneen virran.
• Kun stream_options.include_usage on käytössä, viimeisen osan choices on tyhjä ja se sisältää usage-kentän.
• Virran alkamisen jälkeinen virhe saapuu yhtenä data: {"error": ...} -tapahtumana ilman [DONE]-riviä.

Kutsu ilman suoratoistoa pysäytetään 110 sekunnin jälkeen vastauksella 504 timeout. Lähetä pitkät pyynnöt asetuksella "stream": true.

Käyttö

usage sisältää kentät prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details.cached_tokens ja completion_tokens_details.reasoning_tokens sekä kentän torun_credits: mitä kutsu maksoi Runs-yksiköinä.

Käyttö opencodessa

Kehittäjille-sivun opencode-määritys lisää ToRunin mallintarjoajaksi MCP-palvelimen rinnalle:

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

Mikä tahansa muu OpenAI:n keskustelu-API:a tukeva työkalu toimii samalla tavalla. Sivun OpenAI API -välilehti näyttää tämän kutsun:

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

Miten kutsut maksetaan

API-kutsut maksavat yhtä monta Runs-yksikköä kuin sama käyttö sovelluksessa. Niistä maksavat vain maksetut varat: ensin maksullisen tilauksesi kiintiö ja sitten lompakkosi, jos olet sallinut sen avaimelle. Ilmainen kiintiö ei koskaan maksa API-kutsuja. Avaimen kuukausi- ja päiväraja ovat voimassa, ja vastaukset käyvät läpi turvatarkistuksen samoin kuin keskusteluvastaukset.

Rajat

Jokainen avain voi lähettää tälle API:lle 60 pyyntöä minuutissa ja ajaa 4 completions-pyyntöä samanaikaisesti. Sen ylittyessä API vastaa 429 rate_limit_exceeded ja Retry-After-otsakkeen.

Virheet

Jokainen virhe on muotoa {"error": {"message": ..., "type": ..., "param": ..., "code": ...}}. message on kielellä, jota pyynnön Accept-Language-otsake pyytää.

Pyyntö, jota ei voi maksaa, saa vastauksen 402 eikä 429, jotta asiakas ei yritä sitä uudelleen yhä uudestaan.