Models plane — /v1/chat/completions, /v1/embeddings, /v1/models

The OpenAI-compatible surface ("money plane"). Auth is the same ozk_ key as the rest of the API, sent as Authorization: Bearer ozk_YOUR_KEY only (from Ocean Dashboard → One API → Keys). Errors use the OpenAI error shape {"error":{"message","type","code","request_id"}}.

Drop-in base_url swap

Point the OpenAI SDK you already use at the base URL. That is the entire integration:

Python

from openai import OpenAI
client = OpenAI(base_url="https://api.plungeai.com/v1",
                api_key="ozk_YOUR_KEY")
r = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello"}])
print(r.choices[0].message.content)

TypeScript

import OpenAI from 'openai'
const client = new OpenAI({
  baseURL: 'https://api.plungeai.com/v1',
  apiKey: process.env.PLUNGEAI_API_KEY, // ozk_YOUR_KEY
})
const r = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: 'Hello' }],
})

curl

curl -s https://api.plungeai.com/v1/chat/completions \
  -H "Authorization: Bearer ozk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-5","messages":[{"role":"user","content":"Hello"}]}'

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "anthropic/claude-sonnet-5",
  "choices": [{ "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 8, "completion_tokens": 9, "total_tokens": 17 }
}

Model slugs are provider/model. Get the live priced list from GET /v1/models — never hardcode a slug list from memory. The enforcement is 404 model_not_found: an unknown slug fails, so populate model choices from GET /v1/models at runtime.

Streaming ("stream": true → text/event-stream), any other OpenAI-compatible field (tools, response_format, top_p, …) passes through untouched.

POST /v1/chat/completions — request fields beyond OpenAI's

Routing & failover (models[])

curl -s https://api.plungeai.com/v1/chat/completions \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"models":["anthropic/claude-sonnet-5","openai/gpt-5"],
       "sort":"price",
       "messages":[{"role":"user","content":"Hello"}]}'

• Each candidate gets one retry (2 attempts total) on 429/5xx/network error; backoff honors a short Retry-After (capped 2s) or flat 250ms.
• Exhausting a candidate excludes its provider for 30 seconds and moves to the next; a still-excluded candidate shows "reason":"outage_excluded" in the logged route_attempts (not re-probed).
• A non-429 4xx (your request is malformed) is not retried and not failed over — the next candidate would fail identically.
• Honest billing: the response's model field is the slug that actually served the request — possibly a fallback, not what you asked for first. Bill, log, and display on the response model, never on the requested one.
• Streaming caveat: failover works identically for stream:true — the decision happens on the response status before any bytes are forwarded — but a stream that dies mid-flight is not retried. The model field inside SSE chunks reflects the serving upstream natively; billing still uses the honest slug.

Presets — @preset/<slug>

A stored model+routing+params bundle, addressed via the model field:

curl -s https://api.plungeai.com/v1/chat/completions \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"model":"@preset/fast","messages":[{"role":"user","content":"Hello"}]}'

Request-explicit fields always override the preset — it only fills gaps. Unknown/inactive slug → 404 preset_not_found. Presets are administered platform-side; ask your admin which exist for your org.

Response cache (opt-in, per org)

• Eligible only when temperature: 0 is explicit and stream is not true.
• Cache key = hash of the full request body — any differing field misses.
• Header x-cache: miss (stored for next time) / x-cache: hit (served from cache, never billed, same response id). Header absent entirely when the org has caching off or the request wasn't eligible.
• TTL is per-org, clamped 60s–86400s.

Guardrails & pricing (BYOK-or-billed)

Per-org/per-key policy — spend caps, provider/model allow-lists, content-blocking, BYOK requirements — enforced before cache lookup and before any money moves. Strictest wins when org and key policies overlap.

Pricing: platform-billed by default (provider cost + org markup). Connect your own provider key (BYOK, Dashboard → One API → Catalog → "BYOK provider keys") and requests to that provider route through it for a small routing fee instead. Org policy can require BYOK per provider. Trial orgs are metered but never charged.

Error catalogue

Example 402:

{"error":{"message":"This provider requires your own API key on your plan — connect it in Settings → Integrations, or upgrade to platform-billed usage","type":"byok_required","code":"byok_required","request_id":"00000000-0000-4000-8000-000000000004"}}

POST /v1/embeddings

Same auth, same guardrail enforcement as chat completions.

curl -s https://api.plungeai.com/v1/embeddings \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"model":"openai/text-embedding-3-small","input":["hello world"]}'

{
  "object": "list",
  "data": [{ "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, "..."] }],
  "model": "openai/text-embedding-3-small",
  "usage": { "prompt_tokens": 2, "total_tokens": 2 }
}

input is a string or an array of strings; encoding_format is float or base64. The plane serves openai, mistral, google and cohere embedding models — any other provider is 400 unsupported_provider.

GET /v1/models — the priced catalog

The live list routing candidates are drawn from. Needs the key (/api/v1/models is the public one).

curl -s https://api.plungeai.com/v1/models \
  -H "Authorization: Bearer ozk_YOUR_KEY"

{
  "object": "list",
  "data": [
    { "id": "anthropic/claude-sonnet-5", "object": "model", "owned_by": "anthropic",
      "context_length": 200000, "max_output": 8192,
      "pricing": { "in": 3.0, "out": 15.0 },
      "capabilities": { "streaming": true, "tools": true, "vision": true, "embedding": false, "fim": false },
      "pricing_per_token": { "prompt": "0.000003", "completion": "0.000015" } }
  ]
}

pricing.in / .out are USD per 1M tokens; pricing_per_token is the same price per token as decimal strings. vision: false means not verified, max_output: null means unknown. Generated code that lets users pick a model should populate the choice from this endpoint at runtime, not from a baked-in list. Registry model cards (plungeai_list_agents {kind: "models"}, GET /v1/discovery/search?kind=models) name the same models as provider:model; the plane takes provider/model.

Account, accounting and legacy routes

Same ozk_ key, Authorization: Bearer only.

The /api/v1 drop-in (OpenRouter wire shape)

Point an OpenRouter client at https://api.plungeai.com/api/v1 with the ozk_ key: the same plane (routing, guardrails, cache, billing) under the same eight routes — POST /api/v1/chat/completions, /embeddings, /completions; GET /api/v1/models, /generation, /credits, /key, /models/{author}/{slug}/endpoints. Only the shape differs:

• Errors: {"error":{"code":401,"message":…,"metadata":{"error_type","ocean_code","request_id"}}} — a numeric code, the Ocean code in metadata.ocean_code.
• The completion id is gen-… (also the x-generation-id header); GET /v1/generation?id= takes it.
• GET /api/v1/models is public and lists OpenRouter's item keys (pricing as USD-per-token strings); the /v1/models shape above needs a key.
• The stream sends : OPENROUTER PROCESSING until the first byte and always ends with a usage chunk.
• OpenRouter-only request fields (provider, route, transforms, plugins) are accepted and ignored: route with models[], sort and presets. Cost fields (usage.cost, cost_details, is_byok) appear with usage: {"include": true}; the non-stream price is also the x-ocean-cost-usd header.