Chat completion (proxied to inference-gateway).

/api/v1/chat/completions

Not yet described in the overlay (TI-20).

Authorizations

Authorizationstringheaderrequired

Bearer token: Authorization: Bearer ozk_…. ozk_ platform API key (Authorization: Bearer ozk_…)

Authorizationstringheaderrequired

Bearer token: Authorization: Bearer sk-ocean-…. Legacy sk-ocean- inference key: still accepted on the money plane until the sk-ocean- sunset; new integrations use the ozk_ key

Body

application/json

Money plane, ozk_ 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.

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

Missing or invalid API key

application/json

errorobjectrequired

Show child attributes

codestringrequired

messagestringrequired

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

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)

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

import os import requests response = requests.post( "https://api.plungeai.com/api/v1/chat/completions", headers={"Authorization": f"Bearer {os.environ['PLUNGE_API_KEY']}"}, json={ "messages": [ { "role": "system", "content": "<string>", }, ], }, ) if not response.ok: raise SystemExit(f"{response.status_code} {response.json()['error']['code']}") print(response.json())

import os import requests with requests.post( "https://api.plungeai.com/api/v1/chat/completions", headers={"Authorization": f"Bearer {os.environ['PLUNGE_API_KEY']}"}, json={ "messages": [ { "role": "system", "content": "<string>", }, ], "stream": True, }, stream=True, ) as response: if not response.ok: raise SystemExit(f"{response.status_code} {response.json()['error']['code']}") for line in response.iter_lines(): if line == b"data: [DONE]": break if line: print(line.decode())

const response = await fetch('https://api.plungeai.com/api/v1/chat/completions', { method: 'POST', headers: { Authorization: `Bearer ${process.env.PLUNGE_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "messages": [ { "role": "system", "content": "<string>" } ], "stream": true }), }) if (!response.ok) throw new Error(`${response.status} ${(await response.json()).error?.code}`) const reader = response.body!.getReader() const decoder = new TextDecoder() let buffer = '' read: while (true) { 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) { if (frame.trim() === 'data: [DONE]') break read console.log(frame) } }

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 { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.plungeai.com/api/v1/chat/completions")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_API_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString("{\"messages\":[{\"role\":\"system\",\"content\":\"<string>\"}]}")) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() >= 400) { // Models plane: the machine code is error.code in the JSON body. System.out.println(response.statusCode() + " " + response.body()); return; } System.out.println(response.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 { HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://api.plungeai.com/api/v1/chat/completions")) .header("Authorization", "Bearer " + System.getenv("PLUNGE_API_KEY")) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString("{\"messages\":[{\"role\":\"system\",\"content\":\"<string>\"}],\"stream\":true}")) .build(); HttpResponse<java.util.stream.Stream<String>> response = client.send(request, HttpResponse.BodyHandlers.ofLines()); if (response.statusCode() >= 400) { // Models plane: the machine code is error.code in the JSON body. System.out.println(response.statusCode() + " " + String.join("\n", response.body().toList())); return; } response.body().takeWhile(line -> !line.equals("data: [DONE]")).forEach(System.out::println); } }

curl -X POST 'https://api.plungeai.com/api/v1/chat/completions' \ -H "Authorization: Bearer $PLUNGE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"messages":[{"role":"system","content":"<string>"}]}'

curl -N -X POST 'https://api.plungeai.com/api/v1/chat/completions' \ -H "Authorization: Bearer $PLUNGE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"messages":[{"role":"system","content":"<string>"}],"stream":true}'

Chat completion (proxied to inference-gateway).

Authorizations

Body

Response

Response headers

Planned: TI-33

Planned: TI-34