Provider configuration

Use this reference for provider compatibility flags, authorization, and cost estimates in Aperture.

For provider API formats, setup links, and requirements, refer to the provider matrix in Supported providers and clients.

For client API formats and setup requirements, refer to clients and agent harnesses.

For compatibility restrictions and generic integrations, refer to limitations and other providers and clients.

Compatibility flags

The compatibility object in a provider configuration specifies which API formats the provider supports. These flags determine which endpoints Aperture exposes for the provider's models.

Enable a flag for each API format your provider supports. For example, a Gemini Enterprise Agent Platform provider can use separate flags for Gemini and Anthropic models.

If you enable another flag and omit openai_chat, Aperture disables Chat Completions. Set "openai_chat": true to keep it enabled, or "openai_chat": false to disable it explicitly.

Additional provider fields

Providers also support the optional fields below. Refer to the Aperture configuration reference for all provider fields.

Authorization types

The authorization field selects the upstream header format. Anthropic uses x-api-key, and direct Google Gemini uses x-goog-api-key. The other named providers in the provider matrix use bearer, which is also the default for generic and self-hosted providers.

Credential source

The auth_mode field selects whether Aperture uses the configured apikey or the client's credential. It is independent of authorization, which sets the header format.

A passthrough provider without an apikey is passthrough-only. Its models appear in /v1/models, but not in built-in chat. Chat requests have no client credential to forward. For setup instructions, including subscription-plan OAuth tokens, refer to set up passthrough mode.

Custom headers

Some providers require additional headers beyond the standard authorization field. Use add_headers on the provider to include custom headers in every request Aperture sends to that provider. Each entry is a string in "Header-Name: value" format:

{
  "providers": {
    "example-provider": {
      "baseurl": "https://api.example.com",
      "apikey": "<your-key>",
      "authorization": "bearer",
      "models": ["model-name"],
      "add_headers": [
        "Custom-Header: value"
      ]
    }
  }
}

Cost basis

Aperture estimates the dollar cost of every LLM request. Aperture uses these estimates to deduct request costs from quota balances, populate hook metadata, and show per-model pricing in the Aperture dashboard.

Aperture auto-infers pricing in two steps. It first checks the baseurl host against known gateway hosts. openrouter.ai maps to openrouter, and ai-gateway.vercel.sh maps to vercel. If the host does not match, Aperture falls back to the provider's compatibility flags. For example, anthropic_messages maps to Anthropic pricing.

Set cost_basis explicitly for a regional price source, such as bedrock-eu or azure-eu, or for a custom gateway host.

Use vertex for Gemini Enterprise Agent Platform and azure for both Microsoft Foundry provider types. Generic and self-hosted providers have no dedicated pricing source. With default Chat Completions compatibility, they fall back to openai. Use a model cost map when their model names are absent from that pricing source.

To disable auto-inference globally, set auto_cost_basis to false at the top level of the configuration.

{
  "auto_cost_basis": false,
  "providers": {
    "anthropic": {
      "cost_basis": "anthropic"
    }
  }
}

When auto_cost_basis is false, Aperture estimates token costs only for providers with an explicit cost_basis. Costs reported directly by the upstream gateway remain available.

Model cost map

If a model is missing from the pricing database, use model_cost_map to map its name to a known model:

{
  "providers": {
    "anthropic": {
      "cost_basis": "anthropic",
      "model_cost_map": [
        {"match": "claude-opus-5-*", "as": "claude-opus-4-8"},
        {"match": "claude-*-preview*", "as": "claude-sonnet-4-6", "adjustment": 1.1}
      ]
    }
  }
}

This example prices claude-opus-5-* models like claude-opus-4-8. It prices preview models like claude-sonnet-4-6 with a 10% markup.

Each entry accepts the following fields:

Aperture uses the first matching entry.

Related

• For the complete configuration schema, refer to the Aperture configuration reference.
• For step-by-step provider setup instructions, refer to the set up LLM providers guides.
• For instructions on configuring coding agents to connect through Aperture, refer to the set up LLM clients guides.
• For automated client configuration, refer to the Aperture CLI.
• For connection and request failures, refer to Troubleshooting Aperture.