/ai-provider-openai-sdk

name: ai-provider-openai-sdk
description: Official OpenAI SDK patterns for TypeScript/Node.js — client setup, Chat Completions, Responses API, streaming, structured outputs, function calling, embeddings, vision, audio, and production best practices

OpenAI SDK Patterns

> **Quick Guide:** Use the official `openai` npm package (v6+) to interact with OpenAI's API directly. Use `client.responses.create()` (Responses API) for new projects with built-in tools and server-side state, or `client.chat.completions.create()` (Chat Completions) for stateless chat flows. Use `zodResponseFormat` and `client.chat.completions.parse()` for structured outputs. Use `.stream()` or `stream: true` for streaming. Supports GPT-5.x family, GPT-4o, o4-mini, embeddings, vision, audio, and batch processing.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use the Responses API (`client.responses.create()`) for new projects -- it provides better performance, built-in tools, and server-side conversation state)**

**(You MUST use `zodResponseFormat()` from `openai/helpers/zod` for structured outputs -- do NOT manually construct JSON schemas)**

**(You MUST handle errors using `OpenAI.APIError` and its subclasses -- never use bare catch blocks without error type checking)**

**(You MUST configure appropriate retries and timeouts for production use -- the SDK retries 2 times by default on 429/5xx errors)**

**(You MUST never hardcode API keys -- always use environment variables via `process.env.OPENAI_API_KEY`)**

</critical_requirements>

---

**Auto-detection:** OpenAI, openai, client.chat.completions, client.responses.create, client.responses.parse, client.embeddings, client.audio, zodResponseFormat, zodTextFormat, zodFunction, zodResponsesFunction, runTools, GPT-5, GPT-4o, o4-mini, gpt-5-mini, text-embedding-3, whisper, tts, OPENAI_API_KEY, toFile

**When to use:**

• Building applications that call OpenAI models directly (GPT-5.x, GPT-4o, o4-mini, etc.)
• Implementing chat completions with streaming responses
• Using the Responses API for agentic workflows with built-in tools (web search, file search, code interpreter)
• Extracting structured data from LLM responses with Zod schema validation
• Implementing function calling / tool use with the Chat Completions or Responses API
• Creating embeddings for RAG pipelines or semantic search
• Processing images with vision models or audio with Whisper/TTS
• Running batch jobs for high-volume, cost-efficient processing

**Key patterns covered:**

• Client initialization and configuration (retries, timeouts, proxies)
• Chat Completions API (messages, streaming, function calling)
• Responses API (input, instructions, built-in tools, server-side state)
• Structured outputs with `zodResponseFormat` and `client.chat.completions.parse()`
• Streaming with `for await...of`, `.stream()` helper, and event handling
• Embeddings API (`text-embedding-3-small`, `text-embedding-3-large`)
• Vision (image URLs, base64), Audio (Whisper transcription, TTS), Batch API
• Error handling, retries, timeouts, and production best practices

**When NOT to use:**

• Multi-provider applications where you need to switch between OpenAI, Anthropic, Google, etc. -- use a unified provider SDK instead
• React-specific chat UI hooks (`useChat`, `useCompletion`) -- use a framework-integrated AI SDK
• When you need a higher-level abstraction over multiple LLM providers

---

Examples Index

• [Core: Setup & Configuration](examples/core.md) -- Client init, production config, Azure, error handling, request overrides
• [Chat Completions](examples/chat.md) -- Basic chat, multi-turn, token tracking, output length control
• [Streaming](examples/streaming.md) -- `stream: true`, `.stream()` helper, Responses API streaming, abort
• [Tool/Function Calling](examples/tools.md) -- Manual tools, `zodFunction`, `runTools` automation, Responses API tools
• [Structured Output](examples/structured-output.md) -- `zodResponseFormat`, `zodTextFormat`, refusal handling
• [Embeddings, Vision & Audio](examples/embeddings-vision-audio.md) -- Semantic search, image analysis, transcription, TTS, batch processing
• [Quick API Reference](reference.md) -- Model IDs, method signatures, error types, streaming events

---

<philosophy>

Philosophy

The official OpenAI SDK provides **direct, low-level access** to OpenAI's full API surface. It is the thinnest possible wrapper over the REST API, auto-generated from OpenAI's OpenAPI specification using Stainless.

**Core principles:**

1. **Direct API access** -- No abstractions or provider layers. You get the exact API that OpenAI documents, with full TypeScript types. Every API feature is available immediately when OpenAI releases it. 2. **Two API paradigms** -- The **Responses API** (`client.responses.create()`) is the newer, recommended API with built-in tools and server-side state. The **Chat Completions API** (`client.chat.completions.create()`) remains fully supported for stateless chat flows. 3. **Built-in resilience** -- The SDK handles retries (2 by default on 429/5xx), timeouts (10 min default), and auto-pagination out of the box. 4. **Streaming as a first-class pattern** -- Use `stream: true` for SSE-based streaming, `.stream()` helper for event-based consumption, or `for await...of` for simple iteration. 5. **Type-safe structured outputs** -- `zodResponseFormat()` and `client.chat.completions.parse()` convert Zod schemas to JSON Schema and parse responses, giving you validated, typed objects.

**When to use the OpenAI SDK directly:**

• You only use OpenAI models and want the simplest, most direct integration
• You need access to OpenAI-specific features (Responses API, Batch, Realtime)
• You want minimal dependencies and zero abstraction overhead
• You need the latest API features on day one

**When