V2 API

[opencode-agent]

We are working on redesigning models.dev api

We are going to make a v2 version of our api, this is a master issue to track changes/proposals/requests that will be weighed when developing the new api standard, I will try to keep it up to date as best I can.

Note: v1 api will stay around, we are not breaking the api, v1 will get deprecated eventually but not for a while

---

Below llm generated goop that will get cleaned up as I clarify scope more

Goal

Track the proposed breaking changes for a models.dev API v2. Keep the API compact while making model capabilities, pricing, supported provider APIs, media, lifecycle, and regional availability more accurate.

Proposed changes

• Replace broad non-text modalities with MIME types/patterns.
  • Keep text as the literal text.
  • Include image, PDF, audio, and video MIME types.
  • Preserve separate input and output support.
• Collapse reasoning and reasoning_options into one coherent reasoning field.
• Group tool_call, structured_output, and temperature under capabilities.
  • Missing capability values continue to mean false.
• Keep open_weights as an explicit field; weights links and license metadata are not reliable substitutes.
• Track cache pricing by duration, including 5-minute versus 1-hour writes.
  • Related: Differentiate 5 minute vs 1 hour cache prices #2814.
• Replace the one-off context_over_200k field with the generic conditional pricing mechanism.
• Promote the selectable options currently represented by experimental.modes into a first-class concept for options such as fast, priority, or batch service.
• Add region-aware availability and invocation information.
  • Given an authenticated/configured region, identify which models are usable.
  • Provide the model ID, endpoint/location, SKU, or deployment information needed to invoke them.
  • Account for Bedrock, Vertex, and Azure having different regional semantics.
• Omit deprecated models from API responses by default, with an explicit query option to include/filter them.
• Support additional API query parameters, including provider, status, capabilities, input/output types, family, open weights, and eventually region.
• Remove SDK-specific npm and API shape concepts.
• Replace them with provider-neutral metadata describing which primary APIs can communicate with each model, such as OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Bedrock Converse.

Remove

• attachment
• context_over_200k
• npm
• shape
• The experimental nesting around selectable service/billing modes

Still unsettled

Media

• Keep the name modalities or rename it.
• Decide whether exact MIME types, wildcards, or both are accepted.
• Set the final input/output representation.

Reasoning

• Define the collapsed representation for always-on reasoning, toggles, effort values, and token budgets.

Pricing and selectable modes

• Choose cost, rates, or another pricing term.
• Design one generic mechanism for context thresholds, cache durations, reasoning, media, batch/priority modes, and regional pricing.
• Define units and currency, including image/audio pricing where possible.
• Name the selectable fast/priority/batch concept (modes, tiers, or another term).
• Decide how mode-specific pricing relates to required request body/header changes.
• Decide whether a default mode is explicit.

Regions

• Define provider region registries and reusable groups.
• Define compact model availability expressions.
• Represent regional IDs, endpoints, SKUs, and deployment names without forcing unlike providers into a misleading abstraction.

Limits and usage

• Rework token limits/accounting to cover image and audio usage where providers expose it.
• Handle providers that meter media using different units.

Supported APIs

• Name the field (protocols, apis, or another term).
• Finalize the identifier for OpenAI Chat Completions.
• Decide whether identifiers should be provider-qualified.

Query API

• Choose parameter names and combination semantics.
• Define default status behavior precisely.

Needs triage before inclusion

• Separate model facts from adapter/request wiring such as headers, body overrides, and interleaved handling.
• Add richer lifecycle metadata such as deprecation date, removal date, and replacement model.
• Add source and verification metadata.

Explicit non-goals / decisions

• Do not expose internal base_model inheritance in the public API.
• Do not derive open_weights solely from weights links or license metadata.
• Do not support the legacy OpenAI Completions API in v2; represent Chat Completions only.

[github-actions]

This issue is a design/architecture discussion tracking proposed breaking changes for a future API v2, with many unsettled questions (media, reasoning, pricing, regions, limits, supported APIs, query API) and explicit non-goals. It is not a request to add or correct model/provider metadata in the existing TOML catalog, so no automated data fix applies.

This needs maintainer review; I did not open an automated fix or edit any files.