/openai-api

name: openai-api
description: |
  Build with OpenAI stateless APIs - Chat Completions (GPT-5.2, o3), Realtime voice, Batch API (50% savings), Embeddings, DALL-E 3, Whisper, and TTS. Prevents 16 documented errors.

  Use when: implementing GPT-5 chat, streaming, function calling, embeddings for RAG, or troubleshooting rate limits (429), API errors, TypeScript issues, model name 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