> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai-models

> Model routing on PlungeAI: how agents/workflows/missions resolve a model through the platform's provider factory (`model`/`provider` fields on a task, mission or `POST /v1/agents/{id}/execute`), and the separate OpenAI-compatible money-plane API (`https://api.plungeai.com/v1/chat/completions`…


Model routing on PlungeAI: how agents/workflows/missions resolve a model through the platform's provider factory (`model`/`provider` fields on a task, mission or `POST /v1/agents/{id}/execute`), and the separate OpenAI-compatible money-plane API (`https://api.plungeai.com/v1/chat/completions`, `/v1/embeddings`, `/v1/models`, plus the OpenRouter drop-in `/api/v1`) with your `ozk_` key, `models[]` fallback routing, `@preset/` bundles and response caching for your own code (`ocean-cli models`). Use when steering which model a task/mission runs on, calling chat/embeddings directly from your app, choosing fallback candidates across providers, reading usage/cost (`/v1/generation`, `/v1/credits`), or debugging a 4xx/5xx from `/v1/chat/completions`. For discovering agents/tools/models by capability use `plungeai-discovery`; for running an agent or tool use `plungeai-agents` / `plungeai-tools-connectors`; for authoring CNL workflows that steer `model` per task use `plungeai-workflows`.

[Download zip](https://skills.plungeai.com/plungeai-models.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-models/SKILL.md)

PlungeAI touches models in two distinct places, both opened by your one `ozk_` key:

1. **Inside platform runs** — agents, workflows, and missions resolve models
   through the platform's **provider factory** (a fleet of per-provider
   Workers behind one selection layer). You steer it with `model`/`provider`
   fields on tasks and missions.
2. **The money plane** — an OpenAI-compatible inference API at
   `https://api.plungeai.com` (`/v1/chat/completions`, `/v1/embeddings`,
   `/v1/models`) for YOUR code, with routing/fallback/caching on top.

## Prerequisites

- Self-service `ozk_` key from **Dashboard → One API → Keys**
  (`https://dashboard.plungeai.com`) — the same key opens agents/workflows/MCP and the money plane.
- Legacy `sk-ocean-` model keys are retired: none can be minted, existing ones are read-only under Keys → Legacy keys.
- Base surfaces: `https://mcp.plungeai.com/v1` (MCP) /
  `https://api.plungeai.com` (REST).

## Discovery first

Model catalogs churn weekly. `GET /v1/models` (with your `ozk_` key) is
the priced, live catalog routing candidates are drawn from — discover it at
runtime, never hardcode a model list in generated code.

## 1. Steering the model inside a run (provider factory)

Flat fields on a task, passed through to the agent:

```yaml
- type: task
  id: analyze
  agent: one-agent
  prompt: "…"
  model: claude-sonnet-5
  maxTokens: 4096
```

Or on a harness mission (mission-level override):

```yaml
- type: harness
  agent: one-agent
  goal: "…"
  mission: |
    You are a careful researcher.
  model: claude-sonnet-5
  provider: anthropic
```

Omit `model` and the agent/provider default applies — usually the right
call. Full behavior (pattern-based capability detection so new model
generations work with no platform change, auto-continue on truncation,
per-task usage/cost) — [`references/provider-factory.md`](/skills/plungeai-models/references/provider-factory).

## 2. The money plane for your own code

Drop-in `base_url` swap for any OpenAI-compatible client:

```bash
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": "Say hello"}]}'
```

Ordered fallback across providers, reordered by rolling stats before the
first attempt:

```json
{"models": ["anthropic/claude-sonnet-5", "openai/gpt-5"], "sort": "price",
 "messages": [{"role": "user", "content": "…"}]}
```

Embeddings and the priced catalog:

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

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

Full request fields (`models[]`, `sort`, `@preset/<slug>`, response cache,
guardrails), the complete error catalogue, and streaming —
[`references/money-plane.md`](/skills/plungeai-models/references/money-plane).

## Over the One API — every route of the plane

One `ozk_` key, `Authorization: Bearer` only (no `X-API-Key` here). Setup: `plungeai-api-setup`.

| Route | Does |
|---|---|
| `POST /v1/chat/completions` | OpenAI chat: `model` or `models[]` + `sort`, `@preset/<slug>`, `stream`; the answer's `model` is the slug that served it |
| `POST /v1/messages` | the same money path on the Anthropic Messages wire (`x-api-key` or `Authorization: Bearer`, `system`, `tools`, `tool_use`/`tool_result` blocks, `stream` as `message_start … message_stop` events): any catalog model — `anthropic/*` gets the body as sent, every other model a translation; `anthropic-beta` is not forwarded; errors are Anthropic-shaped (`{type: "error", error: {type, message}, request_id}`) |
| `POST /v1/completions` | legacy text completion: `prompt` is one string |
| `POST /v1/embeddings` | `{model, input}` (string or array); openai, mistral, google and cohere models only (`400 unsupported_provider`) |
| `GET /v1/models` | the priced catalog: `{object: "list", data: [{id, owned_by, context_length, max_output, pricing: {in, out}, capabilities, …}]}`, `pricing` in USD per 1M tokens |
| `GET /v1/models/{author}/{slug}/endpoints` | the one endpoint that serves a model, with per-token pricing; `404 model_not_found` |
| `GET /v1/pricing` | public (no key, cached 60 s): every model Ocean sells — `{object: "list", published_at, data: [{id, mode: "posted" \| "passthrough", list: {in, out}, ocean: {in, out}, discount_pct, offers, …}]}`, USD per 1M tokens; posted models carry Ocean's price and discount against the list price |
| `GET /v1/generation?id=` | usage and cost of one completion (`id` = the `x-request-id`, or the `gen-…` id on `/api/v1`); `404 not_found` for another account's id or one not written yet |
| `GET /v1/credits`, `GET /v1/key` | `{data: {total_credits, total_usage}}` (USD); the calling key's label, monthly limit, usage and rate limit |
| `/api/v1/*` | the same routes in OpenRouter's wire shape for an OpenRouter client: `POST /api/v1/chat/completions`, `/messages`, `/embeddings`, `/completions`, `GET /api/v1/models`, `/generation`, `/credits`, `/key`, `/models/{author}/{slug}/endpoints`; `GET /api/v1/models` is public, errors carry a numeric `code` |

MCP has no tool for the money plane: inside a run you steer the model with `model`/`provider` on
`plungeai_execute_agent`, a task or a harness mission. The CLI spells the plane `ocean-cli models list | chat |
embed`.

What builders get wrong:

- **Two id spellings.** `GET /v1/models` and the execute routes use `provider/model` (`anthropic/claude-sonnet-5`);
  `plungeai_list_agents {kind: "models"}` and `GET /v1/discovery/search?kind=models` return registry cards whose ids
  read `provider:model`. Take the slug from `GET /v1/models`; on the money plane a bare name outside the short alias list is `404 model_not_found`.
- **A pinned model that is not in the catalog fails before the run starts** (`422 unknown_model` on
  `POST /v1/agents/{id}/execute`, with a `hint` to the discovery search) — send `provider` next to `model` so a bare
  name cannot resolve to another provider.
- **Money-plane errors are OpenAI-shaped** (`error.code` is a string such as `invalid_api_key`); execution-plane
  routes use `{error: {code, message}}`, and `/api/v1` uses OpenRouter's numeric `code`. Branch on the HTTP status.
- Cost is opt-in on the response (`usage: {include: true}`); otherwise read the `x-ocean-cost-usd` header or
  `GET /v1/generation`.

## Gotchas

- **One key, Bearer only on the money plane.** The `ozk_` key runs agents/tools/workflows/MCP
  and the money plane; the money plane takes `Authorization: Bearer` only, not `X-API-Key`.
- **Honest billing.** The response `model` field is the slug that ACTUALLY
  served the request — after a failover it can differ from what you asked
  for. Bill, log, and display on the response value, never the requested one.
- **Never hardcode model slugs.** `GET /v1/models` is the only authority;
  populate any model picker in generated code from it at runtime.
- **Nested `config` is a special case.** A `config: {model, maxTokens}` block
  is tolerated by `one-agent` only (call mode flattens it) — use flat task fields
  for every other agent.
- **BYOK and guardrails are trust fences.** `402 byok_required`,
  `403 model_not_allowed`/`content_blocked`, `429 spend_cap_exceeded` — never
  engineer around them; surface and let the human/org decide.

## Related skills

- `plungeai-discovery` — find agents/tools/models/skills live, never from memory.
- `plungeai-agents` — execute a single agent (`model`/`provider` overrides on `plungeai_execute_agent` / `POST /v1/agents/{id}/execute`).
- `plungeai-tools-connectors` — typed tool execution and contracts.
- `plungeai-workflows` — steer `model`/`provider` per task or per harness mission in CNL YAML.
- `plungeai-api-setup` / `plungeai-mcp-setup` — connecting your `ozk_` key in the first place.

## Reference pages

<CardGroup cols={2}>
<Card title="Models plane — /v1/chat/completions, /v1/embeddings, /v1/models" icon="file-text" href="/skills/plungeai-models/references/money-plane">
The OpenAI-compatible surface ("money plane").
</Card>
<Card title="Models — provider factory inside runs, money plane for your code" icon="file-text" href="/skills/plungeai-models/references/provider-factory">
PlungeAI touches models in two distinct places. Keep them apart:
</Card>
</CardGroup>