> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.jambonz.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.jambonz.org/_mcp/server.

# OpenAI

OpenAI's chat completions API (`api.openai.com`) is the de-facto industry standard. If you have a credit card and an OpenAI account, this is the simplest vendor to set up. The `baseURL` override also makes this entry usable for any OpenAI-compatible server — LM Studio, Ollama, vLLM, custom proxies — without a separate vendor.

## Get credentials

1. Sign in at [https://platform.openai.com](https://platform.openai.com).
2. Open **API keys** in the left sidebar (or go directly to [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys)).
3. Click **Create new secret key**, give it a name (e.g. `jambonz`), copy the `sk-...` string.

> **Tip**
>
> OpenAI only shows the key once at creation time. Store it somewhere durable — you can't retrieve it later, only revoke and create a new one.

## Configure in jambonz

In the portal: **Account → LLM Services → + Add LLM Service → OpenAI**.

**`API Key`** `string` — required

The `sk-...` secret you copied from the OpenAI dashboard.

---

**`Base URL`** `string`

Defaults to `https://api.openai.com/v1`. Override only if you're routing through an OpenAI-compatible server (LM Studio, Ollama, vLLM, a corporate proxy, etc.).

---

Click **Test** to verify. A green result means the key authenticates against `/v1/models`.

## Use in an agent verb

```js
session.agent({
  llm: {
    vendor: 'openai',
    model: 'gpt-5.4-mini',
    llmOptions: {
      systemPrompt: 'You are a helpful voice assistant.',
    },
  },
  stt: { vendor: 'deepgram', language: 'en-US' },
  tts: { vendor: 'cartesia', voice: 'sonic-english' },
  turnDetection: 'krisp',
  bargeIn: { enable: true },
  actionHook: '/agent-complete',
}).send();
```

## Available Models

See OpenAI's [model catalog](https://developers.openai.com/api/docs/models/all) for the full list and current pricing. Common picks for voice agents:

| Model          | When to use                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `gpt-5.4-mini` | Default for voice agents — current generation, fast, cheap, tool-capable |
| `gpt-5.4`      | Higher reasoning quality; native computer-use capabilities               |
| `gpt-5.5`      | OpenAI's newest flagship (April 2026)                                    |
| `gpt-4o-mini`  | Previous-generation default; still widely deployed and supported         |
| `gpt-4o`       | Previous-generation flagship                                             |

## Quirks & errors

> **Note**
>
> **gpt-5 / o-series models use `max_completion_tokens`.** OpenAI's reasoning models (o1, o3, o4 family) and gpt-5 require the newer `max_completion_tokens` parameter instead of legacy `max_tokens`. jambonz handles this automatically — passing `maxTokens` in `llmOptions` is forwarded under the right name based on the model id. No action needed on your end.

> **Warning**
>
> **`401 Unauthorized`** typically means the key was revoked or copied with whitespace. Regenerate at [platform.openai.com/api-keys](https://platform.openai.com/api-keys) and update the credential in the portal.

> **Warning**
>
> **`429 Too Many Requests`** means you've hit a rate limit or your account's monthly quota. Add a payment method or upgrade tier at [platform.openai.com/account/billing](https://platform.openai.com/account/billing).

> **Tip**
>
> Pointing jambonz at a self-hosted OpenAI-compatible server? Set the **Base URL** field to your endpoint (e.g. `http://localhost:11434/v1` for Ollama). The API key field still has to be non-empty even if your server doesn't enforce auth — pass any string.