> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model providers

> Configure Gemini, Vertex AI, and OpenAI-compatible providers for declarative agents.

Hyperterse resolves model providers per agent from `model.provider`, `model.model`, and `model.options`.

## Provider matrix

| Provider value                | Backend                                        |
| ----------------------------- | ---------------------------------------------- |
| `gemini`, `google_ai_studio`  | Gemini via Google AI Studio                    |
| `vertex`, `vertex_ai`         | Gemini via Vertex AI                           |
| `openai_compatible`, `openai` | OpenAI-compatible `/chat/completions` endpoint |

When an agent loads, Hyperterse normalizes provider values (lowercased; `-` becomes `_`).

## Option keys and env behavior

| Key        | Used by                           | Behavior / fallback                                                                                                               |
| ---------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`  | Gemini, Vertex, OpenAI-compatible | Inline key value. Supports `{{ env.VAR_NAME }}` substitution. If unset, Hyperterse falls back to each provider's default env var. |
| `base_url` | OpenAI-compatible                 | Base URL; defaults to `https://api.openai.com/v1` when unset.                                                                     |
| `project`  | Vertex                            | Vertex project id; fallback `GOOGLE_CLOUD_PROJECT`.                                                                               |
| `location` | Vertex                            | Vertex location; fallback `GOOGLE_CLOUD_LOCATION`, then `GOOGLE_CLOUD_REGION`.                                                    |

Model option string values support `{{ env.VAR_NAME }}` substitution when the agent model is initialized.

## Gemini (Google AI Studio)

```yaml theme={null}
model:
  provider: gemini
  model: gemini-2.5-flash
```

Supported auth options:

* `api_key` (inline or `{{ env.VAR_NAME }}` substitution)
* fallback env: `GOOGLE_API_KEY` (recommended)

## Vertex AI

```yaml theme={null}
model:
  provider: vertex_ai
  model: gemini-2.5-pro
  options:
    project: my-gcp-project
    location: us-central1
```

Resolution behavior:

* `project` option or env `GOOGLE_CLOUD_PROJECT`
* `location` option or env `GOOGLE_CLOUD_LOCATION`, fallback `GOOGLE_CLOUD_REGION`
* optional `api_key` support, fallback `GOOGLE_API_KEY`

## OpenAI-compatible

```yaml theme={null}
model:
  provider: openai_compatible
  model: gpt-4o-mini
  options:
    base_url: https://api.openai.com/v1
    api_key: '{{ env.OPENAI_API_KEY }}'
```

Resolution behavior:

* `base_url` defaults to `https://api.openai.com/v1`
* key from `api_key`, fallback `OPENAI_API_KEY`

## Other popular providers

Direct means you can use `openai_compatible` with that provider's
OpenAI-compatible endpoint directly. Indirect means you should put a compatibility
gateway in front first.

<Tip>
  For production, run a quick smoke test with your exact model and one tool call
  before rollout.
</Tip>

| Provider        |                                 Status |
| --------------- | -------------------------------------: |
| OpenAI Platform |    <Badge color="green">Direct</Badge> |
| OpenRouter      |    <Badge color="green">Direct</Badge> |
| Together AI     |    <Badge color="green">Direct</Badge> |
| Groq            |    <Badge color="green">Direct</Badge> |
| Fireworks AI    |    <Badge color="green">Direct</Badge> |
| DeepSeek        |    <Badge color="green">Direct</Badge> |
| Mistral         |    <Badge color="green">Direct</Badge> |
| Perplexity      |    <Badge color="green">Direct</Badge> |
| xAI             |    <Badge color="green">Direct</Badge> |
| LiteLLM gateway |    <Badge color="green">Direct</Badge> |
| Azure OpenAI    | <Badge color="yellow">Indirect</Badge> |
| Anthropic       | <Badge color="yellow">Indirect</Badge> |
| Gemini / Vertex | <Badge color="yellow">Indirect</Badge> |

### OpenAI compatibility

`openai_compatible` is defined by protocol behavior, not by vendor name.

#### Accepted provider identifiers

After normalization (lowercase, with `-` converted to `_`), Hyperterse accepts:

* `openai_compatible` (canonical)
* `openai` (alias)

#### Required protocol contract

For direct integration, the target endpoint must support:

* `POST {base_url}/chat/completions`
* `Authorization: Bearer <token>`
* OpenAI-compatible request/response payloads
* OpenAI-compatible tool-call payloads when tools are enabled

#### Direct vs indirect usage

Use `openai_compatible` directly only when the contract above is satisfied.
Use a compatibility gateway when any of these differ:

* endpoint path
* auth mechanism (for example non-Bearer or required custom headers)
* payload/response/tool-call schema

## Production-safe examples

### Gemini with env-managed key

```yaml theme={null}
model:
  provider: gemini
  model: gemini-2.5-flash
```

### Vertex with explicit project/location

```yaml theme={null}
model:
  provider: vertex_ai
  model: gemini-2.5-pro
  options:
    project: my-gcp-project
    location: us-central1
```

### OpenAI-compatible with custom gateway

```yaml theme={null}
model:
  provider: openai_compatible
  model: gpt-4o-mini
  options:
    base_url: https://my-gateway.example.com/v1
```

### OpenRouter with a free model

```yaml theme={null}
model:
  provider: openai_compatible
  model: openai/gpt-oss-20b:free
  options:
    base_url: https://openrouter.ai/api/v1
    api_key: '{{ env.OPENROUTER_API_KEY }}'
```

## Recommended patterns

* Keep secrets in provider default env vars (`OPENAI_API_KEY`, `GOOGLE_API_KEY`) instead of inline literals.
* Pin `model` values deliberately per agent role (cheap vs reasoning-heavy).
* Add one agent per workflow role rather than reusing a single all-purpose prompt.

<Warning>
  Avoid committing inline `api_key` values to source control. Prefer provider
  default env vars and managed secret injection in deployment.
</Warning>

For full agent shape, see [Agent configuration reference](/reference/agent-config) and [Quickstart](/agents/quickstart).