Create chat completion

/v1/chat/completions

Examples verified against code, not live (TI-78). The models plane takes an sk-ocean- key ($PLUNGE_MODEL_KEY); an ozk_ key answers 401 invalid_api_key. Errors carry error.code in the body, never an X-Error-Code header.

Authorizations

Authorizationstringheaderrequired

Bearer token: Authorization: Bearer sk-ocean-…. sk-ocean- inference key (money plane, forwarded downstream)

Body

application/json

Money plane, sk-ocean- auth. Transparent proxy to inference-gateway — any OpenAI-compatible field is passed through untouched; the fields below are the ones Phase 2 routing adds on top.

modelstring

A single model slug ("provider/model", e.g. "anthropic/claude-sonnet-5"), or "@preset/<slug>" to expand a stored model+routing+params bundle (request-explicit fields below still override the preset). Ignored if models[] is set.

modelsstring[]

Ordered fallback candidates — alternative to model. One retry per candidate on 429/5xx/network, then failover to the next; a candidate whose provider just failed out is excluded for 30s.

sortenum<string>

Reorders models[] before the first attempt. latency/throughput sort by rolling provider stats; a provider with no history yet sorts last.

Available options: price, latency, throughput

messagesChatMessage[]required

Show child attributes

roleenum<string>required

Available options: system, user, assistant, tool

contentstringrequired

streamboolean

Default: false

temperaturenumber

Set to exactly 0 to make the request response-cache eligible.

max_tokensinteger

top_pnumber

Response

Completion (model = the slug that actually served it, not necessarily the one requested). stream:true returns text/event-stream instead — see the developer guide for the streaming caveat.

application/json
text/event-stream

Response headers

x-cacheenum<string>

"miss" or "hit" — present only when the org has response caching enabled and the request was cache-eligible (temperature:0, stream not true); absent otherwise.

x-request-idstringfrom code

Server-minted request id.

x-cachestringfrom code

miss or hit when the opt-in response cache is on.

idstringrequired

objectstringrequired

modelstringrequired

The model that served this response — bill and log both key on this value.

choicesobject[]required

usageobject

Show child attributes

prompt_tokensinteger

completion_tokensinteger

total_tokensinteger

The body failed validation; error.code is in the body (no X-Error-Code on the models plane).

Error code: invalid_request_errorfrom code

Missing/invalid sk-ocean- key

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

byok_required — this provider needs your own connected key on this plan

Error code: insufficient_balancefrom code

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

model_not_allowed (routing candidates excluded by an allow-list) or content_blocked (prompt matched a guardrail regex)

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

preset_not_found — @preset/<slug> does not exist or is inactive

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

rate_limit_exceeded (per-key/per-provider) or spend_cap_exceeded (guardrail cap reached)

Error code: insufficient_quotafrom code

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

money_plane_unavailable — INFERENCE_GATEWAY_SERVICE not bound on this tier

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

Stream events

Event	Description
`chat.completion.chunk`	One delta of the completion in `choices[0].delta`.
`[DONE]`	End of the stream.

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"hi"},"finish_reason":null}]}

data: [DONE]

import os import requests res = requests.post( 'https://api.plungeai.com/v1/chat/completions', headers={'Authorization': f"Bearer {os.environ['PLUNGE_MODEL_KEY']}"}, json={'model': 'openai/gpt-4o-mini', 'messages': [{'role': 'user', 'content': 'hi'}], 'max_tokens': 8}, ) body = res.json() if res.status_code != 200: raise SystemExit(body['error']['code']) print(body['choices'][0]['message']['content'])

import json import os import requests with requests.post( 'https://api.plungeai.com/v1/chat/completions', headers={'Authorization': f"Bearer {os.environ['PLUNGE_MODEL_KEY']}"}, json={'model': 'openai/gpt-4o-mini', 'messages': [{'role': 'user', 'content': 'hi'}], 'max_tokens': 8, 'stream': True}, stream=True, ) as res: for line in res.iter_lines(decode_unicode=True): if not line or not line.startswith('data: '): continue data = line[len('data: '):] if data == '[DONE]': break delta = json.loads(data)['choices'][0]['delta'] print(delta.get('content', ''), end='', flush=True)

const res = await fetch('https://api.plungeai.com/v1/chat/completions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.PLUNGE_MODEL_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'openai/gpt-4o-mini', messages: [{ role: 'user', content: 'hi' }], max_tokens: 8, stream: true }), }) const reader = res.body!.getReader() const decoder = new TextDecoder() let buffer = '' for (;;) { const { done, value } = await reader.read() if (done) break buffer += decoder.decode(value, { stream: true }) const frames = buffer.split('\n\n') buffer = frames.pop() ?? '' for (const frame of frames) { const data = frame.replace(/^data: /, '') if (data === '[DONE]') process.exit(0) process.stdout.write(JSON.parse(data).choices[0].delta.content ?? '') } }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Main { public static void main(String[] args) throws Exception { String json = "{\"model\":\"openai/gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}],\"max_tokens\":8}"; HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.plungeai.com/v1/chat/completions")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_MODEL_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString()); System.out.println(res.statusCode() + " " + res.body()); } }

import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class Main { public static void main(String[] args) throws Exception { String json = "{\"model\":\"openai/gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}],\"max_tokens\":8,\"stream\":true}"; HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.plungeai.com/v1/chat/completions")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_MODEL_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(json)) .build(); HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofLines()).body() .filter(line -> line.startsWith("data: ")) .takeWhile(line -> !line.equals("data: [DONE]")) .forEach(System.out::println); } }

curl -s https://api.plungeai.com/v1/chat/completions \ -H "Authorization: Bearer $PLUNGE_MODEL_KEY" \ -H 'Content-Type: application/json' \ -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":8}'

curl -sN https://api.plungeai.com/v1/chat/completions \ -H "Authorization: Bearer $PLUNGE_MODEL_KEY" \ -H 'Content-Type: application/json' \ -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}],"max_tokens":8,"stream":true}'

import os from openai import OpenAI client = OpenAI(api_key=os.environ["PLUNGE_MODEL_KEY"], base_url="https://api.plungeai.com/v1") completion = client.chat.completions.create( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "hi"}], max_tokens=8, ) print(completion.choices[0].message.content)

import os from openai import OpenAI client = OpenAI(api_key=os.environ["PLUNGE_MODEL_KEY"], base_url="https://api.plungeai.com/v1") stream = client.chat.completions.create( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "hi"}], max_tokens=8, stream=True, ) for chunk in stream: print(chunk.choices[0].delta.content or "", end="")

import OpenAI from 'openai' const client = new OpenAI({ apiKey: process.env.PLUNGE_MODEL_KEY, baseURL: 'https://api.plungeai.com/v1' }) const completion = await client.chat.completions.create({ model: 'openai/gpt-4o-mini', messages: [{ role: 'user', content: 'hi' }], max_tokens: 8, }) console.log(completion.choices[0].message.content)

import OpenAI from 'openai' const client = new OpenAI({ apiKey: process.env.PLUNGE_MODEL_KEY, baseURL: 'https://api.plungeai.com/v1' }) const stream = await client.chat.completions.create({ model: 'openai/gpt-4o-mini', messages: [{ role: 'user', content: 'hi' }], max_tokens: 8, stream: true, }) for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? '')

Create chat completion

Authorizations

Body

Response

Response headers

Stream events

Planned: TI-33

Planned: TI-34