Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs-site/src/content/docs/guides/web-dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -493,6 +493,8 @@ maintainers do not provide policy advice and cannot resolve provider enforcement
measured usage. Active user `modelCosts` overlays take priority over bundled verified catalog and
price fallbacks, and historical usage is re-estimated from the pricing active when the summary is
read. The cost is an estimate for reconciliation, not a ChatGPT Plus/Pro subscription invoice.
A model with no bundled price is priced from the public models.dev or OpenRouter list and marked as
an online-list estimate; a manual price always wins.
Historical bare `openai` rows that predate explicit attribution remain ambiguous rather than being
assigned to the current main account.
- **Target a specific Codex account from the model picker** is an explicit opt-in. When enabled,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -374,6 +374,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
| `defaultMaxOutputTokens?` | `number` | Provider-wide `openai-chat` fallback when the client omits `max_output_tokens`. An `anthropic` row without it uses the registry output cap of the Claude model it serves (64000 for any model on `api.anthropic.com`), and 8192 for a model id the registry does not list. A value you set here, or in `modelMaxOutputTokens`, always wins. |
| `modelMaxOutputTokens?` | `Record<string, number>` | Positive per-model `openai-chat` fallback budgets; exact/pattern matches beat the provider default. |
| `modelCosts?` | `Record<string, ProviderCostOverlay>` | Per-model display prices (USD per 1M tokens), keyed by that provider's exact upstream model id — not a provider identifier or a routed `provider/model` label, e.g. `{ "deepseek-v4-flash": { "input": 0.14, "output": 0.28, "cacheRead": 0.0028, "cacheWrite": 0 } }`. Any model id is a valid key — custom providers may target any OpenAI-compatible endpoint through the `openai-chat` adapter, and local or internal provider ids work even when they are absent from the built-in catalogs. User-configured prices win over the built-in catalogs in the Logs `~$` and Usage estimates; historical entries are repriced from the current overlay, so editing a price can move past totals. The fallback order is user `modelCosts` → exact official correction → jawcode catalog → expected-price overlay → model-level vendor fallback, and an explicit all-zero user entry means a known-zero estimate; delete that model entry to restore automatic pricing. All-zero catalog metadata still falls through. Each rate must be a non-negative finite number at most 1,000,000 (USD per 1M tokens); out-of-range rows are rejected by the management boundary and dropped on load. Display-time estimation only: overlays never affect routing, account selection, quotas, or billing. |
| `priceMultiplier?` | `number` | Opt-in relay multiplier (finite, greater than 0, at most 1000) applied to this provider's automatic prices (official, models.dev, OpenRouter) in the cost estimate, for a relay that marks prices up or down. Never applied to `modelCosts`. Absent means 1. |
| `headers?` | `Record<string, string>` | Extra upstream headers. For the classic OpenAI web-search sidecar, `x-openai-internal-codex-responses-lite` is removed case-insensitively after configured and selected headers are merged; other forwarded headers are preserved. Authorization, cookies, API-key headers, embedded newlines, and invalid names are rejected. Requests that ride the provider outbound wrapper — model discovery, connection tests, and other proxy-originated diagnostics such as the Ollama show probe — send `User-Agent: opencodex` unless a User-Agent is set here or by the provider preset. An experimental relay may negotiate earlier completed-tool delivery with `x-opencodex-tool-completion: block-stop-v1`; the embedding shell must supply authenticated durable turn membership, and the relay must acknowledge the same response header and implement exact call-bound completion markers. Leave it unset for other providers. Early delivery applies only to eligible structured calls; later errors or cancellation cannot retract a call already delivered. |
| `forwardClientHeaders?` | `string[]` | `openai-responses` only: opt in to copying named inbound client metadata headers onto inference requests when the provider has not already set that header. Credential and transport-owned names such as `Authorization`, cookies, API-key headers, `Content-Type`, `Content-Length`, `Host`, and `x-oai-attestation` are rejected and also filtered at runtime. Header names are case-insensitive and may not repeat. `headers` remains authoritative; the existing caller `User-Agent` fallback still applies when neither surface sets one. Supported names: `originator`, `x-client-request-id`, `x-codex-app-version`, `user-agent`, `x-codex-window-id`, `x-codex-installation-id`; all other names are refused. |
| `supportsNativeCompactionTrigger?` | `boolean` | `openai-responses` only: declare support for native v2 `compaction_trigger` input items. Defaults off for noncanonical gateways; preserves native compaction rather than requesting a portable text summary. Independent of the v1 endpoint and blob replay capabilities. |
Expand Down Expand Up @@ -1837,6 +1838,8 @@ contracts.

The raw provider editor and provider API expose this map. POST/PUT replace an explicitly supplied map and reject null entries. PATCH merges individual axes; null clears a map, model, axis or video processing value, while `{}` makes no change. Omitted provider overwrites preserve the existing map. Malformed hand-edited files retain valid independent axes and treat malformed explicit input modalities as text-only, with a diagnostic.

`modelCapabilityProbes` is written by the [capability probe](/reference/management-api/#capability-probe), not by hand. Keyed by model ID, each entry records `probedAt` (ISO 8601 UTC) and `inputModalities: true` and/or `reasoningEfforts: true` for the declarations (`modelCapabilities.<id>.inputModalities`, `modelReasoningEfforts.<id>`) that came from a live probe. A manual edit of that declaration through the dashboard or management API removes its label, a label is removed when its declaration is gone, and the field is absent when empty. A malformed value is dropped at load with a warning.

An explicit `modelCapabilities.<id>.inputModalities` now takes precedence over legacy modality hints for that exact routed model. A text-only declaration uses the existing vision sidecar to replace images with descriptions; if no sidecar is available, the request receives an explicit omission marker before dispatch. Native Chat image requests divert through this path. The catalog can still advertise image attachment support because the proxy provides the description step. Context-tier and video processing declarations remain inert pending their transport support.

An input-modality declaration on a **custom model row** — the Input modalities checkboxes in the
Expand Down
98 changes: 97 additions & 1 deletion docs-site/src/content/docs/reference/management-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -552,6 +552,37 @@ All four rates must be finite numbers from 0 through 1,000,000, in USD per 1M to
Unknown fields and malformed rates are rejected. A write preserves other models' overrides
and returns `{ ok: true, provider, modelId, cost }`; reset returns `cost: null`.

### Automatic prices

A model with no manual price is priced, in this order, from a verified official price, then the
public models.dev list, then the public OpenRouter list. The two public lists are fetched in the
background (at most daily, plus one fetch when a model no source could price is first seen), never
on a request path, and cached in `price-catalog-cache.json` in the OpenCodex home. Offline, the
previous snapshot keeps answering. A price from a public list is always an estimate. A manual price
always wins and is never scaled.

Each non-combo row of `GET /api/models` carries `price` when a price is known and omits it when not:
`{ source, input, output, cacheRead, cacheWrite }` in USD per 1M tokens, where `source` is `manual`,
`official`, `models-dev` or `openrouter`. A public-list price also carries `fetchedAt` (ISO time).
`multiplier` appears when the provider's relay multiplier was applied, and `apiEquivalent: true` when
the provider bills through a subscription, so the figure is what the same tokens would cost on the API.

`POST /api/pricing/refresh` forces an immediate refresh of both public lists, clears the retry
cooldowns for models that could not be priced, and returns
`{ ok: true, sources: { "models-dev": status, "openrouter": status } }`. A source `status` is
`{ ok: true, fetchedAt, count }` or `{ ok: false, error }`, where `error` is a short code such as
`fetch_failed`, `bad_json`, `empty` or `http_503`, never a response body.

`PUT /api/providers/{provider}/price-multiplier` accepts `{ multiplier }`, a finite number greater
than 0 and at most 1000, or `null` to remove it, and returns `{ ok: true, provider, multiplier }`.
The multiplier models a relay that charges a markup or discount over the vendor's list price. It
scales official, models.dev and OpenRouter prices for that provider and never a manual price.
`GET /api/providers/{provider}/model-costs` also returns `priceMultiplier` when one is set. An unset
multiplier is absent from `config.json`; an invalid stored value is ignored at load with a warning.

`/api/logs` and `/api/usage` cost results add the reasons `online_price_catalog`,
`relay_price_multiplier` and `subscription_api_equivalent` to `estimateReasons` when they apply.

The **Model price** dialog offers **Automatic**, **Flat rate**, and **Custom threshold**
prompt-length pricing. Automatic (also the default when the policy is absent) retains catalog
context rules with the saved base rates. Flat disables context adjustments. Custom selects four
Expand Down Expand Up @@ -647,7 +678,21 @@ maps these facts come from. Display name is not part of this route; use

`GET /api/models` reports the exact stored `contextWindowDeclared` separately from the
effective `contextWindow`. The Models editor starts from the declaration and shows the effective
window as an inherited hint when no declaration exists. If a save outcome is unknown, or the
window as an inherited hint when no declaration exists.

Routed rows also carry `capabilitySources`, one label per axis (`contextWindow`,
`inputModalities`, `reasoningEfforts`): `manual` (an operator declaration), `probed` (a
declaration written by the capability probe), `reported` (discovery, the registry or provider
metadata), `inferred` (a context window the catalog estimated under `inferContextWindow`), or
`unknown`. When the same model id is known elsewhere, `inferredCapabilities` carries the estimate
for each axis as `{ value, basis: { source, provider, modelId } }`, where `source` is `registry`
(a built-in original-vendor provider), `vendor` (bundled vendor metadata), `provider` (another
configured provider's declaration) or `aggregator` (bundled aggregator metadata), in that order of
authority. Ids match ignoring case, a `vendor/` prefix, dot-versus-hyphen spelling and a `[...]`
suffix; two sources of the same authority that disagree give no estimate. These estimates are
display data: they never route a request and never enter the Codex catalog on their own. To use
one, save it as a declaration (the model-settings route, `modelCapabilities`, or
`modelReasoningEfforts`) or, for the context window, enable `inferContextWindow`. If a save outcome is unknown, or the
save succeeded but the model list did not reload, the dialog disables further writes and offers
a read-only Reload. After a successful reload, reopen the row to inspect the stored values.
A `catalogRefresh` that failed, or was skipped with `retryable: true`, leaves the save in place and
Expand Down Expand Up @@ -770,6 +815,7 @@ already read.
| `PATCH /api/providers?name=...` | Update allowed provider fields (including a merged `headers` block), enabled/default state, or OpenAI account mode | 400 invalid field or transition; 404 unknown provider |
| `DELETE /api/providers?name=...` | Delete a provider, reassigning the default when possible | 404 unknown provider; 409 `last_provider`; 409 `provider_has_dependent_combos` |
| `POST /api/providers/test?name=...` | Perform a bounded live provider connectivity/model-discovery probe | 404 unknown provider; failures are normally returned as `ok: false` evidence |
| `POST /api/providers/probe-capabilities` | Probe whether one model accepts an image input and which reasoning efforts it accepts, optionally writing the conclusive results back as labeled declarations (see [Capability probe](#capability-probe)) | 400 invalid request; 404 unknown provider; 409 probe already running for that provider |
| `GET /api/provider-quotas` | Read provider quota reports; `refresh=1` forces refresh | — |
| `GET /api/quota-pool` | Read the passive `ocx.quota-pool/1` account quota pool (per-account and pooled windows, opaque account references) from cached evidence only; never probes or refreshes, and ignores `refresh`. Pooled windows are a plan-weighted estimate over the routable accounts' readings from the last 30 minutes, plus an `availability` window while no account can run. Also readable from a Remote Link Child or Hub client at `/api/machine/hub-relay/api/quota-pool` | — |
| `GET /api/quota-resets` | List recently detected quota-window resets and whether detection is enabled; `limit=<n>` caps the count | 400 invalid `limit` |
Expand All @@ -784,6 +830,56 @@ also preserves an omitted setting, including the latest stored `false`; an expli
boolean wins. See [Context windows on custom providers](/reference/configuration/providers/#context-windows-on-custom-providers)
for its default-off, custom-provider-only behavior.

#### Capability probe

`POST /api/providers/probe-capabilities` sends a few tiny live requests to one model on one
configured provider. It reuses the explicit completion diagnostic (`openai-chat` and
`openai-responses` wires only, 32-token output cap, 20-second deadline per request, no retries),
changing only the request body. A plain prompt is sent first as a baseline; one probe adds a 1x1 PNG image beside the prompt, and one probe
per reasoning effort adds `reasoning_effort` (Chat) or `reasoning.effort` (Responses).

Request body:

```json
{ "name": "my-provider", "model": "vendor/model", "checks": ["image", "reasoning"],
"efforts": ["low", "medium", "high"], "confirmMetered": true, "apply": false }
```

- `checks` defaults to both. `efforts` is valid only with the `reasoning` check, accepts declared
effort names (`none`, `minimal`, `low` … `ultra`, at most 6), and defaults to the model's
configured ladder, else `low`, `medium`, `high`.
- A provider that authenticates with an API key and points at a non-local destination is
**metered**. Without `confirmMetered: true` nothing is sent and the response is
`{ "applicable": true, "sent": false, "requiresConfirmation": true, "metered": true, "plannedRequests": n }`.
- OAuth, forward-auth, disabled, and unsupported-adapter providers answer
`{ "applicable": false, "reason": ..., "sent": false }` without sending.

When sent, the response is `{ applicable: true, sent: true, metered, provider, model, baseline, image?, reasoning?, applied? }`:

- `baseline.status` reports the plain prompt. Unless it is `accepted`, no variant is sent and every
check is `inconclusive`, so an unrelated 400 (an unknown model, say) is never read as "this model
rejects images". `plannedRequests` counts the baseline.

- `image.status` is `accepted` (the request completed), `rejected` (HTTP 400 or 422), or
`inconclusive` (timeout, network, 401/403/429/5xx, or an incomplete stream); `image.error`
carries only `{ code, status? }`.
- `reasoning` lists efforts under `accepted`, `rejected`, and `inconclusive`. A reasoning probe that
finishes without text still counts as accepted: the request was admitted and the small output cap
can be spent entirely on reasoning.
- Probes run one at a time. A 401, 403, or 429 (or a missing or changed credential) stops the run,
and the remaining efforts are reported as inconclusive.
- "Accepted" means the upstream did not refuse the field; a gateway that silently ignores
`reasoning_effort` reads as accepting every effort. Upstream response and error bodies are never
returned or logged.

With `apply: true`, conclusive results are saved and the Codex catalog is refreshed, as after a
provider PATCH. An accepted image writes `modelCapabilities[model].inputModalities = ["text", "image"]`,
a rejected one `["text"]`; other capability axes are untouched. The reasoning ladder is written to
`modelReasoningEfforts[model]` (accepted efforts in ladder order) only when every probed effort was
conclusive. `applied` reports what was written. Each written axis is labeled in the provider's
`modelCapabilityProbes` field; a later manual edit of that axis through `PATCH /api/providers`
(`modelCapabilities`) or `PUT /api/model-settings` removes the label.

When Antigravity's quota-summary endpoint has no usable response, quota reports may also include
per-model Cloud Code Assist usage windows when the model-discovery response provides them. These
measurements are diagnostic; an absent model window does not establish that the model is unavailable.
Expand Down
Loading
Loading