V2 API

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

• Keep modalities with nested input and output arrays, replacing broad non-text modalities with exact MIME types and wildcard MIME patterns.
  • Keep text as the literal text.
  • Include image, PDF, audio, and video MIME types.
  • Providers should publish the narrowest accurate value.
• Collapse reasoning and reasoning_options into one object:
  • reasoning.supported is a required boolean indicating whether this is a reasoning model.
  • reasoning.options is a required array of the existing tagged reasoning configuration options.
  • Use an empty options array when reasoning is unsupported or has no request-time configuration.
• 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: #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.
• Add an api namespace for provider-model invocation metadata.
  • api.formats describes supported provider-neutral API formats such as OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Bedrock Converse.
  • Format-specific wire metadata lives beneath its format entry.
  • For OpenAI-compatible reasoning round trips, use api.formats.<format>.reasoning.field for fields such as reasoning, reasoning_content, or reasoning_details.
  • Omit the format-specific reasoning object when no special reasoning field is required.

Remove

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

Still unsettled

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.
• Handle off-peak pricing

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

• 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

• Revisit first-class model type/purpose metadata after higher-priority contract work.
  • Related: #3028.
• Decide which remaining headers and body overrides belong under api.formats versus staying internal adapter metadata.
• 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.