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, /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 (opens in a new tab) · View raw SKILL.md (opens in a new tab)

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:

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

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

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

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

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

Over the One API — every route of the plane

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

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