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 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.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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:

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

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

- 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:

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:

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

Embeddings and the priced catalog:

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.

Reference pages