openai sdk

OpenAI SDK is the official Python and TypeScript client library for the OpenAI API — providing type-safe access to GPT models, DALL-E image generation, Whisper transcription, embeddings, and fine-tuning endpoints — with synchronous, asynchronous, and streaming interfaces that serve as the de facto standard for LLM API integration across the industry.

What Is the OpenAI SDK?

• Definition: The official client library (openai Python package, openai npm package) maintained by OpenAI for interacting with their REST API — handling authentication, HTTP communication, error handling, retries, and response parsing.
• Python SDK (v1.0+): Introduced in late 2023, the v1.0 rewrite moved from module-level functions to a client object pattern — `client = OpenAI()` then `client.chat.completions.create()` — with strict typing via Pydantic and better IDE completion.
• TypeScript/Node SDK: The `openai` npm package mirrors the Python API exactly — same method names, same parameter names — enabling easy skill transfer between languages.
• OpenAI-Compatible Standard: The OpenAI API format has become the industry standard — LiteLLM, Ollama, Azure OpenAI, Together AI, Anyscale, and dozens of other providers expose OpenAI-compatible endpoints, making SDK knowledge universally applicable.
• Async Support: Full async/await support via `AsyncOpenAI` client — critical for high-throughput applications processing thousands of concurrent API calls.

Why the OpenAI SDK Matters

• Industry Standard Interface: Learning the OpenAI SDK means understanding the interface that powers the majority of production LLM applications — Azure OpenAI, Together AI, Groq, and Anyscale all use the same API format.
• Type Safety: v1.0+ SDK uses Pydantic models for all responses — IDE autocomplete, runtime validation, and no more raw dictionary access with potential KeyError.
• Streaming: First-class streaming support enables real-time response display — users see tokens as they generate rather than waiting for the full completion.
• Built-in Retries: Automatic exponential backoff and retry on rate limit errors (429) and server errors (500/503) — production reliability without custom retry logic.
• Tool Use / Function Calling: Structured tool calling enables LLMs to request data from external systems — the foundation for all agent frameworks.

Core Usage Patterns

Basic Chat Completion:

from openai import OpenAI

client = OpenAI()  # Uses OPENAI_API_KEY env variable

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum entanglement simply."}
    ],
    max_tokens=500,
    temperature=0.7
)
print(response.choices[0].message.content)

Streaming Response:

with client.chat.completions.stream(model="gpt-4o", messages=[...]) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Tool Calling (Function Calling):

tools = [{"type": "function", "function": {
    "name": "get_weather",
    "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
}}]
response = client.chat.completions.create(model="gpt-4o", messages=[...], tools=tools)
# Check response.choices[0].message.tool_calls for tool invocation

Async Usage:

from openai import AsyncOpenAI
import asyncio

async_client = AsyncOpenAI()
async def fetch(prompt):
    return await async_client.chat.completions.create(model="gpt-4o-mini", messages=[{"role":"user","content":prompt}])

Embeddings:

embedding = client.embeddings.create(model="text-embedding-3-small", input="Sample text")
vector = embedding.data[0].embedding  # 1536-dimensional float list

Key API Capabilities

• Chat Completions: Multi-turn conversation with system, user, and assistant roles — the core interface for all conversational AI.
• Structured Outputs: Pass a JSON schema or Pydantic model via `response_format` — guaranteed valid structured output (no Instructor needed for simple schemas).
• Embeddings: Convert text to high-dimensional vectors for semantic search, clustering, and classification.
• DALL-E 3 Image Generation: Generate and edit images from text prompts via `client.images.generate()`.
• Whisper Transcription: Audio file to text via `client.audio.transcriptions.create()`.
• Fine-Tuning: Upload training data and fine-tune GPT-4o-mini or GPT-3.5 via `client.fine_tuning.jobs.create()`.
• Batch API: Submit thousands of requests for 50% cost reduction with 24-hour processing via `client.batches.create()`.

SDK v0 vs v1 Migration

The OpenAI SDK is the lingua franca of LLM application development — mastering its patterns for streaming, tool calling, structured outputs, and async usage provides skills that transfer directly to Azure OpenAI, Groq, Together AI, and any other OpenAI-compatible provider, making it the most leveraged API investment in the AI engineering toolkit.