Create chat completion

/api/v1/chat/completions

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.

modelstringrequired

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). Required unless models[] is set, which replaces it.

Example: "openai/gpt-4o-mini"

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

Example: "user"

contentstringrequired

Example: "Say hi in three words"

streamboolean

Default: false

temperaturenumber

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

max_tokensinteger

Example: 16

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

invalid_json — body is not valid JSON; invalid_request_error — the gateway rejected the request (a missing or malformed field)

application/json

errorobjectrequired

Show child attributes

codeintegerrequired

The HTTP status

messagestringrequired

metadataobjectrequired

Show child attributes

error_typestringrequired

OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …

ocean_codestringrequired

The /v1 envelope's string error.code

ocean_typestring

request_idstringrequired

Equals the x-request-id header

Missing or invalid API key

application/json

errorobjectrequired

Show child attributes

codeintegerrequired

The HTTP status

messagestringrequired

metadataobjectrequired

Show child attributes

error_typestringrequired

OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …

ocean_codestringrequired

The /v1 envelope's string error.code

ocean_typestring

request_idstringrequired

Equals the x-request-id header

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

application/json

errorobjectrequired

Show child attributes

codeintegerrequired

The HTTP status

messagestringrequired

metadataobjectrequired

Show child attributes

error_typestringrequired

OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …

ocean_codestringrequired

The /v1 envelope's string error.code

ocean_typestring

request_idstringrequired

Equals the x-request-id header

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

application/json

errorobjectrequired

Show child attributes

codeintegerrequired

The HTTP status

messagestringrequired

metadataobjectrequired

Show child attributes

error_typestringrequired

OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …

ocean_codestringrequired

The /v1 envelope's string error.code

ocean_typestring

request_idstringrequired

Equals the x-request-id header

preset_not_found — @preset/<slug> does not exist or is inactive; model_not_found — no such model in the catalog

application/json

errorobjectrequired

Show child attributes

codeintegerrequired

The HTTP status

messagestringrequired

metadataobjectrequired

Show child attributes

error_typestringrequired

OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …

ocean_codestringrequired

The /v1 envelope's string error.code

ocean_typestring

request_idstringrequired

Equals the x-request-id header

method_not_allowed — the path serves one method: the Allow header names it, plus OPTIONS

application/json

Response headers

Allowstring

The method this path serves, plus OPTIONS

errorobjectrequired

Show child attributes

codeintegerrequired

The HTTP status

messagestringrequired

metadataobjectrequired

Show child attributes

error_typestringrequired

OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …

ocean_codestringrequired

The /v1 envelope's string error.code

ocean_typestring

request_idstringrequired

Equals the x-request-id header

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

application/json

errorobjectrequired

Show child attributes

codeintegerrequired

The HTTP status

messagestringrequired

metadataobjectrequired

Show child attributes

error_typestringrequired

OpenRouter's error type: authentication, payment_required, rate_limit_exceeded, not_found, invalid_request, …

ocean_codestringrequired

The /v1 envelope's string error.code

ocean_typestring

request_idstringrequired

Equals the x-request-id header

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={ "model": "openai/gpt-4o-mini", "messages": [ { "role": "user", "content": "Say hi in three words", }, ], }, ) 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={ "model": "openai/gpt-4o-mini", "messages": [ { "role": "user", "content": "Say hi in three words", }, ], "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({ "model": "openai/gpt-4o-mini", "messages": [ { "role": "user", "content": "Say hi in three words" } ], "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("{\"model\":\"openai/gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hi in three words\"}]}")) .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("{\"model\":\"openai/gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hi in three words\"}],\"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 '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Say hi in three words"}]}'

curl -N -X POST 'https://api.plungeai.com/api/v1/chat/completions' \ -H "Authorization: Bearer $PLUNGE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Say hi in three words"}],"stream":true}'

{ "error": { "code": 0, "message": "<string>", "metadata": { "error_type": "<string>", "ocean_code": "<string>", "ocean_type": "<string>", "request_id": "<string>" } } }

Create chat completion

Authorizations

Body

Response

Response headers

Response headers

Planned: TI-33

Planned: TI-34