Model management

Use this workflow for every model change. Keep the implementation minimal, preserve the public contract unless the user explicitly approves a change, and prove provider behavior with real requests.

Load context first

1. Read the repository AGENTS.md.
2. Read the live registry entry, runtime config, handler, schemas, and tests. The repository is the source of truth for what Pollinations currently offers.
3. Read the relevant local active plan when present:

- temp/manageinference.md - temp/manageinferenceport.md - temp/managegpus.md - temp/manageazure_limits.md

1. Check GitHub for open or merged PRs that may already implement or conflict with the work.
2. Check current official provider documentation, catalog, pricing, availability, quotas, and deprecation notices. Then probe the exact route; the live response wins over documentation.

The temp plans are ignored operational state, not repository truth. When working in a linked worktree where they are absent, locate the primary checkout with git worktree list and read them there. Never copy balances, prices, PR statuses, quotas, or candidate rankings into this skill.

Read [operating-policy.md](references/operating-policy.md) before recommending a route or model. Read only the other references needed for the task:

Mandatory confirmation gate

Apply this gate only to a proposed tracked model mutation. Do not turn a read-only status confirmation, an approval of an already-documented planning decision, or a correction of an operational fact into a different mutation. Treat a generic “confirm” as approval only for the exact contract just shown.

Do not edit any model until the user confirms its complete business and inference contract. Inspect the code and provider first; do not ask the user to discover values for you.

Show one complete row per model:

Ask:

Please confirm: canonical name X, aliases A/none, price multiplier M, paid-only yes/no, Pollinations GPU yes/no, registry provider P, primary route R, best fallback candidate C/none found, and Pollinations fallback decision use C/none. Are all of these correct?

An answer approves only the values shown. If a value is unknown, inferred, conflicting, or route-dependent, label it UNKNOWN, explain the evidence, and wait for that exact decision. A batch approval is valid only when every row is complete.

Public API changes require separate confirmation

Model approval does not authorize adding, renaming, removing, or changing a public endpoint, method, transport, request or response schema, streaming behavior, or event protocol. Do not propose an API-surface change without a concrete user or developer problem it solves.

Before editing, present:

• the user/developer problem and the current public contract;
• the exact proposed routes, methods, transports, schemas, streaming behavior, and events;
• the compatibility reference, resolved by the order in step 4;
• whether the change is additive, behavioral, deprecating, or breaking, and the affected clients;
• the migration, coexistence, and removal plan, or none.

State plainly: This adds/changes the public API: ... Then ask for explicit confirmation of that exact API change. If the problem, standard, or compatibility impact is unclear, do not edit.

Secrets are a separate approval

Model approval never authorizes adding, rotating, synchronizing, deploying, revoking, or otherwise mutating a credential. Follow the exact approval wording, dedicated-PR requirement, execution order, verification, and rollback rules in AGENTS.md. Do not duplicate or weaken that process here.

Workflow

1. Reconcile current state

• Resolve aliases to the canonical registry entry.
• Before any canonical rename, count production and staging API keys whose

permissions.models contains the old canonical ID. Registry aliases do not preserve restricted-key access because authorization compares the resolved canonical ID.

• Audit every modality registry and every model change merged to main since

the current production revision; production can lag behind main.

• Trace every reachable runtime route and any configured fallback.
• Distinguish the configured provider from the provider that served an observed request.
• Compare the intended change with open PRs and active plan entries.
• Remove shipped work from active plans after production verification; do not keep a completed archive.

2. Research the exact route

• Use official provider/model sources for release, model identity, pricing, regions, preview status, quotas, rate limits, context, inputs, outputs, tools, caching, and deprecation.
• Deduplicate the canonical model across providers.
• List material route differences. Equal model names do not prove equal capabilities.
• Probe the exact deployment and request shape Pollinations will use.
• For every addition or modification, run a fresh web search across provider catalogs and official documentation to discover viable fallback routes; do not rely only on repository integrations or remembered availability. Verify each serious candidate against its current official model page and pricing, then probe the exact route. Compare checkpoint identity, capabilities, parameters, formats, safety/privacy, availability, latency, price, permissions, and billing. Recommend the best candidate or state none found; never omit the fallback decision because the primary route is healthy.
• Inspect provider-managed routing/fallback defaults and controls. Report identity, capability, pricing, residency, and observability tradeoffs.

3. Confirm the contract

Present the mandatory row and obtain explicit confirmation before editing. If a capability or access change is intentional, state it plainly.

4. Implement the smallest complete change

• Canonical public IDs use lowercase

<publisher-slug>/<official-model-slug> and preserve the official family and version. Keep provider deployment IDs and routing internal.

• Reuse existing handlers, transforms, provider configs, schemas, and generic fallback infrastructure.
• Implement only the explicitly approved fallback decision. Use the shared generic fallback system for an approved pair; do not add a model-specific retry layer or an unapproved fallback.
• Expose a confirmed new public capability (per the API-change confirmation above) through two surfaces backed by one implementation: a Pollinations-native route outside /v1 and a standard-compatible route under /v1.
• Resolve the compatibility contract in this order: (1) current official OpenAI API; (2) if OpenAI defines no equivalent, the current published OpenRouter contract — a protocol-design reference here, not an inference-provider fallback; (3) if neither defines the capability, stop for an explicit API-contract decision. Document the exact reference checked.
• Treat /v1 as a compatibility namespace: match the selected standard's route, transport, request, response, streaming, and event contracts exactly, and keep provider-specific protocols behind the route adapters — never a Pollinations-specific or upstream-provider schema under /v1.
• Prefer the selected standard's schema on the Pollinations-native route too; deliberate native divergence requires its own explicit API-change confirmation.
• Do not collapse capabilities with materially different inputs, outputs, or transports into one endpoint merely by switching model. Keep distinct operations separate while reusing their shared internal handler, authorization, billing, and observability paths.
• Treat aliases as identity-only: resolve to the canonical model, then discard the requested alias for behavior. Never infer parameters from alias spelling such as -high, -search, -reasoning, or -1080p; only explicit request parameters and canonical defaults apply. Keep a separate canonical model if the old behavior must remain.
• Use the resolved registry entry for canonical model identity in generic handlers. Never maintain handler-level lists of model IDs for response, tracking, billing, or routing behavior.
• Canonicalize all stale stored aliases found by the same registry-wide audit in

one D1 migration PR. Replace old IDs, preserve unrelated permission fields and array order, deduplicate old/new pairs, prove idempotence, and verify all audited old-ID counts are zero after deployment.

• Keep every migration statement within D1's per-query CPU limit: one statement

per alias, and prefilter with instr() inside CASE so JSON functions never run on non-matching rows. A single whole-table JSON scan fails with error 7429 at production scale (~150k apikey rows).

• API-key create and update paths must store recognized aliases as canonical

IDs, while preserving unknown and community IDs, so migrations do not need to repair newly written aliases again.

• For a pending canonical rename, merge the migration before the model PR but

do not promote the replacement-only migration while production still resolves the old ID. Promote a revision containing both changes so D1 runs immediately before the Worker deploy. Keep mappings in migrations only; do not add a runtime normalization layer.

• Update every consumer of a changed public ID at once.
• Add aliases only for existing compatibility contracts or explicit approval.
• Add models to MODEL_SLUGS.md only when renaming a historical public ID.
• Keep one PR per model or tightly coupled model-family change.
• Never edit generated APIDOCS.md; update the source schema or route.

5. Verify end to end

• Run the relevant rows in [change-and-test-matrix.md](references/change-and-test-matrix.md).
• For new models and provider/model-ID changes, run the full declared-modality matrix and [billing-verification.md](references/billing-verification.md).
• Test aliases, permissions, errors, caching, capacity, and /models metadata.
• When a fallback is configured, probe it directly and run the same applicable E2E matrix through a forced fallback, including capabilities, parameters, permissions, cache behavior, billing, provider attribution, errors, and expected burst. When no fallback is approved, record the researched candidate and rejection reason.
• Verify all media is fully returned within the supported request-lifetime budget, including the durable-media checks when applicable.
• Record exact evidence and uncertainty in the PR.

6. Open the PR

Before publishing:

• Format changed files with the repository formatter.
• Run focused tests and type checks for every touched service.
• Review the complete diff for unrelated changes and dead code.
• Include the approved contract, exact primary and fallback candidates, fallback decision, pricing sources, live probes, E2E results, billing evidence, capacity results, limitations, and deprecation/quota gates.
• Leave the PR draft when a live, quota, latency, safety, or product decision remains unresolved.

Completion gate

A model change is not complete until all applicable statements are true:

• The configured model, aliases, provider, route, price, access, modalities, and capabilities match the approved contract.
• Direct-provider and local E2E requests passed for every declared surface.
• The best fallback candidate and use/decline decision are documented; every configured fallback passed direct and forced-fallback E2E verification.
• No existing capability disappeared unless explicitly approved.
• Every non-zero usage field is accounted for and billed at the confirmed rate.
• Malformed or rejected requests return useful 4xx responses rather than opaque 5xx responses.
• Capacity and media latency fit the expected production load.
• The catalog description is developer-facing, does not repeat the title, and the brand logo resolves.
• No public API surface was added or changed without its separate explicit confirmation.
• No unapproved secret or deployment mutation occurred.
• The PR contains only this model or tightly coupled family.