---
name: plungeai-models
description: "Model routing on PlungeAI: how agents/workflows/missions resolve a model through the platform's provider factory (`model`/`provider` fields on a task or mission), and the separate OpenAI-compatible money-plane API (`https://api.plungeai.com/v1/chat/completions`, `/v1/embeddings`, `/v1/models`) with `sk-ocean-` keys, `models[]` fallback routing, `@preset/` bundles, and response caching for your own code. Use when steering which model a task/mission runs on, calling chat/embeddings directly from your app, choosing fallback candidates across providers, 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`."
---

# PlungeAI Models

PlungeAI touches models in two distinct places, with two different keys:

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 (execution planes: agents/workflows/MCP) from
  **Dashboard → One API → Keys** (`https://dashboard.plungeai.com`).
- The money plane uses a **different key**: `sk-ocean-` (same dashboard).
  Mixing the two up is the most common 401.
- Base surfaces: `https://mcp.plungeai.com/v1` (MCP) /
  `https://api.plungeai.com` (REST).

## Discovery first

Model catalogs churn weekly. `GET /v1/models` (with an `sk-ocean-` 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: llm-agent
  prompt: "…"
  model: claude-sonnet-5
  maxTokens: 4096
```

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

```yaml
- type: harness
  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`.

## 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 sk-ocean-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 sk-ocean-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 sk-ocean-YOUR_KEY"
```

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

## Gotchas

- **Two key types.** `ozk_` runs agents/tools/workflows/MCP; `sk-ocean-` runs
  the money plane. A key from the wrong tier 401s.
- **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 `llm-agent` only (it 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 an `ozk_`/`sk-ocean-` key in the first place.