openai

---
name: openai
description: OpenAI API for GPT models. Use when user mentions "OpenAI", "GPT", "ChatGPT
  API", or asks about OpenAI models (do NOT use for Anthropic/Claude).
---

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name OPENAI_TOKEN` or `zero doctor check-connector --url https://api.openai.com/v1/chat/completions --method POST`

## How to Use

All examples below assume you have `OPENAI_TOKEN` set.

Base URL: `https://api.openai.com/v1`

### 1. Basic Chat Completion

Send a simple chat message:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "Hello, who are you?"}]
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.choices[0].message.content'
```

**Available models:**

- `gpt-4o`: Latest flagship model (128K context)
- `gpt-4o-mini`: Fast and affordable (128K context)
- `gpt-4-turbo`: Previous generation (128K context)
- `gpt-3.5-turbo`: Legacy model (16K context)
- `o1`: Reasoning model for complex tasks
- `o1-mini`: Smaller reasoning model

### 2. Chat with System Prompt

Use a system message to set behavior:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant that responds in JSON format."},
    {"role": "user", "content": "List 3 programming languages with their main use cases."}
  ]
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.choices[0].message.content'
```

### 3. Streaming Response

Get real-time token-by-token output:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "Write a haiku about programming."}],
  "stream": true
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json
```

Streaming returns Server-Sent Events (SSE) with delta chunks.

### 4. JSON Mode

Force the model to return valid JSON:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "Return JSON only."},
    {"role": "user", "content": "Give me info about Paris: name, country, population."}
  ],
  "response_format": {"type": "json_object"}
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.choices[0].message.content'
```

### 5. Vision (Image Analysis)

Analyze an image with GPT-4o:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"}}
      ]
    }
  ],
  "max_tokens": 300
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.choices[0].message.content'
```

### 6. Function Calling (Tools)

Define functions the model can call:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "What is the weather in Tokyo?"}],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }
  ]
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.choices[0].message.tool_calls'
```

### 7. Generate Embeddings

Create vector embeddings for text:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "text-embedding-3-small",
  "input": "The quick brown fox jumps over the lazy dog."
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/embeddings" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.data[0].embedding[:5]'
```

This extracts the first 5 dimensions of the embedding vector.

**Embedding models:**

- `text-embedding-3-small`: 1536 dimensions, fastest
- `text-embedding-3-large`: 3072 dimensions, most capable

### 8. Generate Image

Create an image from text using GPT-Image 2.0 (recommended) or DALL-E 3:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-image-2",
  "prompt": "A white cat sitting on a windowsill, digital art",
  "n": 1,
  "size": "1024x1024",
  "quality": "high",
  "output_format": "png"
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/images/generations" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.data[0].b64_json' -r | base64 -d > /tmp/generated_image.png
```

**Image models:**

- `gpt-image-2`: Latest model, highest quality, supports transparent backgrounds and flexible sizes
- `dall-e-3`: Previous generation, simpler interface

**Parameters (gpt-image-2):**

- `size`: `1024x1024`, `1536x1024`, `1024x1536`, or `auto` (default). Supports any size where max edge < 3840px, both edges are multiples of 16, and ratio ≤ 3:1
- `quality`: `low`, `medium`, `high`, or `auto` (default)
- `output_format`: `png`, `jpeg`, or `webp` (default: `png`)
- `output_compression`: 0–100, only with `jpeg` or `webp`
- `background`: `transparent`, `opaque`, or `auto` (default)
- `moderation`: `low` (less restrictive) or `auto` (default)
- `n`: 1–10 images per call
- `response_format`: `b64_json` (gpt-image-2 always returns base64)
- `stream`: `true` for streaming mode with `partial_images` (0–3) progress updates

**Parameters (dall-e-3):**

- `size`: `1024x1024`, `1792x1024`, or `1024x1792`
- `quality`: `standard` or `hd`
- `style`: `vivid` or `natural`

### 9. Audio Transcription (Whisper)

Transcribe audio to text:

```bash
curl -s "https://api.openai.com/v1/audio/transcriptions" -H "Authorization: Bearer $OPENAI_TOKEN" -F "file=@audio.mp3" -F "model=whisper-1" | jq '.text'
```

Supports: mp3, mp4, mpeg, mpga, m4a, wav, webm (max 25MB).

### 10. Text-to-Speech

Generate audio from text:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "tts-1",
  "input": "Hello! This is a test of OpenAI text to speech.",
  "voice": "alloy"
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/audio/speech" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json --output speech.mp3
```

**Voices:** `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`

**Models:** `tts-1` (fast), `tts-1-hd` (high quality)

### 11. List Available Models

Get all available models:

```bash
curl -s "https://api.openai.com/v1/models" -H "Authorization: Bearer $OPENAI_TOKEN" | jq -r '.data[].id' | sort | head -20
```

### 12. Check Token Usage

Extract usage from response:

Write to `/tmp/openai_request.json`:

```json
{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "Hi!"}]
}
```

Then run:

```bash
curl -s "https://api.openai.com/v1/chat/completions" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_TOKEN" -d @/tmp/openai_request.json | jq '.usage'
```

This returns token counts for both input and output.

Response includes:

- `prompt_tokens`: Input token count
- `completion_tokens`: Output token count
- `total_tokens`: Sum of both

## Guidelines

1. **Choose the right model**: Use `gpt-4o-mini` for most tasks, `gpt-4o` for complex reasoning, `o1` for advanced math/coding
2. **Set max_tokens**: Prevent runaway generation and control costs
3. **Use streaming for long responses**: Better UX for real-time applications
4. **JSON mode requires system prompt**: Include JSON instructions when using `response_format`
5. **Vision requires gpt-4o models**: Only `gpt-4o` and `gpt-4o-mini` support image input
6. **Batch similar requests**: Use embeddings API batch input for efficiency
7. **Monitor usage**: Check dashboard regularly to avoid unexpected charges