/openai-api

name: openai-api
description: "Use when implementing GPT chat, streaming, function calling, embeddings for RAG, images, audio or batch jobs, or troubleshooting 429 rate limits and API or TypeScript errors. Stateless OpenAI patterns that prevent 16 documented errors."
user-invocable: true
domain: engineering

OpenAI API - Complete Guide

**Version**: Production Ready ✅ **Package**: openai@6.16.0 **Last Updated**: 2026-01-20

---

Status

**✅ Production Ready**:

• ✅ Chat Completions API (GPT-5, GPT-4o, GPT-4 Turbo)
• ✅ Embeddings API (text-embedding-3-small, text-embedding-3-large)
• ✅ Images API (DALL-E 3 generation + GPT-Image-1 editing)
• ✅ Audio API (Whisper transcription + TTS with 11 voices)
• ✅ Moderation API (11 safety categories)
• ✅ Streaming patterns (SSE)
• ✅ Function calling / Tools
• ✅ Structured outputs (JSON schemas)
• ✅ Vision (GPT-4o)
• ✅ Both Node.js SDK and fetch approaches

---

Table of Contents

1. [Quick Start](#quick-start) 2. [Chat Completions API](#chat-completions-api) 3. [GPT-5 Series Models](#gpt-5-series-models) 4. [Streaming Patterns](#streaming-patterns) 5. [Function Calling](#function-calling) 6. [Structured Outputs](#structured-outputs) 7. [Vision (GPT-4o)](#vision-gpt-4o) 8. [Embeddings API](#embeddings-api) 9. [Images API](#images-api) 10. [Audio API](#audio-api) 11. [Moderation API](#moderation-api) 12. [Error Handling](#error-handling) 13. [Rate Limits](#rate-limits) 14. [Common Mistakes & Gotchas](#common-mistakes--gotchas) 15. [TypeScript Gotchas](#typescript-gotchas) 16. [Production Best Practices](#production-best-practices) 17. [Relationship to openai-responses](#relationship-to-openai-responses)

---

Quick Start

Installation

npm install openai@6.16.0

Environment Setup

export OPENAI_API_KEY="sk-..."

Or create `.env` file:

OPENAI_API_KEY=sk-...

First Chat Completion (Node.js SDK)

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const completion = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'user', content: 'What are the three laws of robotics?' }
  ],
});

console.log(completion.choices[0].message.content);

First Chat Completion (Fetch - Cloudflare Workers)

const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.OPENAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5',
    messages: [
      { role: 'user', content: 'What are the three laws of robotics?' }
    ],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);

---

Chat Completions API

**Endpoint**: `POST /v1/chat/completions`

The Chat Completions API is the core interface for interacting with OpenAI's language models. It supports conversational AI, text generation, function calling, structured outputs, and vision capabilities.

Supported Models

GPT-5 Series (Released August 2025)

• **gpt-5**: Full-featured reasoning model with advanced capabilities
• **gpt-5-mini**: Cost-effective alternative with good performance
• **gpt-5-nano**: Smallest/fastest variant for simple tasks

GPT-4o Series

• **gpt-4o**: Multimodal model with vision capabilities
• **gpt-4-turbo**: Fast GPT-4 variant

GPT-4 Series (Legacy)

• **gpt-4**: Original GPT-4 model *(deprecated - use gpt-5 or gpt-4o)*

Basic Request Structure

{
  model: string,              // Model to use (e.g., "gpt-5")
  messages: Message[],        // Conversation history
  reasoning_effort?: string,  // GPT-5 only: "minimal" | "low" | "medium" | "high"
  verbosity?: string,         // GPT-5 only: "low" | "medium" | "high"
  temperature?: number,       // NOT supported by GPT-5
  max_tokens?: number,        // Max tokens to generate
  stream?: boolean,           // Enable streaming
  tools?: Tool[],             // Function calling tools
}

Response Structure

{
  id: string,                 // Unique completion ID
  object: "chat.completion",
  created: number,            // Unix timestamp
  model: string,              // Model used
  choices: [{
    index: number,
    message: {
      role: "assistant",
      content: string,        // Generated text
      tool_calls?: ToolCall[] // If function calling
    },
    finish_reason: string     // "stop" | "length" | "tool_calls"
  }],
  usage: {
    prompt_tokens: number,
    completion_tokens: number,
    total_tokens: number
  }
}

Message Roles & Multi-turn Conversations

Three roles: **system** (behavior), **user** (input), **assistant** (model responses).

**Important**: API is **stateless** - send full conversation history each request. For stateful conversations, use `openai-responses` skill.

---

GPT-5 Series Models

GPT-5 models (released August 2025) introduce reasoning and verbosity controls.

GPT-5.2 (Released December 11, 2025)

**Latest flagship model**:

• **gpt-5.2**: 400k context window, 128k output tokens
• **xhigh reasoning_effort**: New level beyond "high" for complex problems
• **Compaction**: Extends context for long workflows (via API endpoint)
• **Pricing**: $1.75/$14 per million tokens (1.4x of GPT-5.1)

// GPT-5.2 with maximum reasoning
const completion = await openai.chat.completions.create({
  model: 'gpt-5.2',
  messages: [{ role: 'user', content: 'Solve this extremely complex problem...' }],
  reasoning_effort: 'xhigh', // NEW: Beyond "high"
});

GPT-5.1 (Released November 13, 2025)

**Warmer, more intelligent model**:

• **gpt-5.1**: Adaptive reasoning that varies thinking time dynamically
• **24-hour extended prompt caching**: Faster follow-up queries at lower cost
• **New developer tools**: apply_patch (code editing), shell (command execution)

**BREAKING CHANGE**: GPT-5.1/5.2 default to `reasoning_