OpenAI SDK Development Skill

Quick Reference

OpenAI SDK development with Python and TypeScript/JavaScript clients. Covers GPT-5 family models, Chat Completions API, Responses API, embeddings, tool calling, and streaming.

Progressive Disclosure: This file provides quick reference patterns. See REFERENCE.md for comprehensive API coverage, advanced patterns, and deep dives.

---

Table of Contents

1. When to Use
2. GPT-5 Model Family
3. Quick Start
4. Chat Completions API
5. Responses API (Next Gen)
6. Tool Calling
7. Embeddings
8. Error Handling
9. Platform Differentiators
10. Further Reading
11. Context7 Integration

---

When to Use

This skill is loaded by backend-developer when:

• openai package in requirements.txt or pyproject.toml
• openai in package.json dependencies
• Environment variables OPENAI_API_KEY present
• User mentions "OpenAI", "GPT", or "ChatGPT" in task

---

GPT-5 Model Family

Model Selection Guide

| Model | Context | Best For | Cost | |-------|---------|----------|------| | gpt-5.2 | 400K | Flagship - coding, agentic, multimodal | $1.75/$14 | | gpt-5.2-pro | 400K | Maximum reasoning (xhigh effort) | $21/$168 | | gpt-5.1 | 256K | Stable, previous generation | $1.50/$12 | | gpt-5.1-codex | 256K | Long-running coding tasks | $1.50/$12 | | gpt-5 | 128K | General purpose | $1.25/$10 | | gpt-4o | 128K | Fast, cost-effective | $2.50/$10 | | gpt-4o-mini | 128K | Cheapest, simple tasks | $0.15/$0.60 |

Costs per 1M tokens (input/output). Cached input: 50-90% discount.

Quick Selection

Simple chat/Q&A           -> gpt-4o-mini
Standard tasks            -> gpt-4o or gpt-5
Complex reasoning         -> gpt-5.1 with reasoning_effort="high"
Coding/agentic           -> gpt-5.2 or gpt-5.1-codex
Maximum intelligence      -> gpt-5.2-pro with reasoning_effort="xhigh"

Reasoning Effort (GPT-5.1+)

reasoning_effort = "none"    # Fast, no reasoning
reasoning_effort = "low"     # Light reasoning
reasoning_effort = "medium"  # Default
reasoning_effort = "high"    # Extended reasoning
reasoning_effort = "xhigh"   # Maximum (GPT-5.2 Pro only)

---

Quick Start

Python Setup

from openai import OpenAI

# Client auto-uses OPENAI_API_KEY env var
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

TypeScript Setup

import OpenAI from 'openai';

const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: 'gpt-5',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' }
  ]
});

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

Async Python

import asyncio
from openai import AsyncOpenAI

async def main():
    client = AsyncOpenAI()
    response = await client.chat.completions.create(
        model="gpt-5",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)

asyncio.run(main())

---

Chat Completions API

Basic Completion

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Python?"}
    ],
    temperature=0.7,
    max_tokens=1000
)

answer = response.choices[0].message.content
usage = response.usage  # tokens used

Message Roles

| Role | Description | |------|-------------| | system | Sets behavior/context (first message) | | user | Human input | | assistant | Model responses | | tool | Tool/function results |

Common Parameters

| Parameter | Type | Description | |-----------|------|-------------| | model | string | Model ID (e.g., "gpt-5") | | messages | array | Conversation messages | | temperature | 0-2 | Randomness (0=deterministic) | | max_tokens | int | Max response tokens | | stream | boolean | Enable streaming | | response_format | object | JSON mode | | tools | array | Tool definitions | | reasoning_effort | string | Reasoning level (GPT-5.1+) |

JSON Mode

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "Return JSON only."},
        {"role": "user", "content": "List 3 programming languages."}
    ],
    response_format={"type": "json_object"}
)

data = json.loads(response.choices[0].message.content)

Streaming

stream = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Tell me a story."}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

---

Responses API (Next Gen)

The Responses API provides built-in tools, conversation continuity, and chain-of-thought passing between turns.

When to Use

| Use Case | API | |----------|-----| | Simple chat/completion | Chat Completions | | Built-in web search | Responses API | | Built-in code interpreter | Responses API | | Conversation continuity (CoT) | Responses API |

Basic Usage

response = client.responses.create(
    model="gpt-5",
    input="Explain quantum computing simply."
)

print(response.output_text)

Built-in Tools

# Web search
response = client.responses.create(
    model="gpt-5",
    input="What are the latest AI news today?",
    tools=[{"type": "web_search"}]
)

# Code interpreter
response = client.responses.create(
    model="gpt-5",
    input="Calculate factorial of 20 and plot it",
    tools=[{"type": "code_interpreter"}]
)

Conversation Continuity

# First turn
response1 = client.responses.create(
    model="gpt-5",
    input="My name is Alice and I'm a software engineer."
)

# Continue - CoT passes between turns
response2 = client.responses.create(
    model="gpt-5",
    input="What do I do for work?",
    previous_response_id=response1.id
)

---

Tool Calling

Quick Tool Definition

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string", "description": "City, country"},
                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
            },
            "required": ["location"],
            "additionalProperties": False
        },
        "strict": True
    }
}]

Basic Tool Loop

import json

def get_weather(location: str, unit: str = "celsius") -> dict:
    return {"temperature": 22, "conditions": "sunny", "unit": unit}

# Initial request
response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=tools
)

message = response.choices[0].message

# Process tool calls if present
if message.tool_calls:
    messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]
    messages.append(message)

    for tool_call in message.tool_calls:
        args = json.loads(tool_call.function.arguments)
        result = get_weather(**args)

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)
        })

    # Get final response
    final = client.chat.completions.create(
        model="gpt-5",
        messages=messages
    )
    print(final.choices[0].message.content)

Tool Choice Options

tool_choice = "auto"      # Model decides
tool_choice = "none"      # No tools
tool_choice = "required"  # Must use at least one
tool_choice = {"type": "function", "function": {"name": "get_weather"}}  # Force specific

---

Embeddings

Generate Embeddings

response = client.embeddings.create(
    model="text-embedding-3-large",
    input="The quick brown fox",
    dimensions=1024  # Optional: reduce dimensions
)

vector = response.data[0].embedding

Embedding Models

| Model | Dimensions | Use Case | |-------|------------|----------| | text-embedding-3-large | 3072 (default) | Highest quality | | text-embedding-3-small | 1536 (default) | Cost-effective |

Batch Embeddings

texts = ["Hello world", "How are you?", "Goodbye"]

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)

embeddings = [d.embedding for d in response.data]

---

Error Handling

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | AuthenticationError | Invalid API key | Check OPENAI_API_KEY | | RateLimitError | Too many requests | Implement backoff | | InvalidRequestError | Bad parameters | Validate inputs | | APIConnectionError | Network issues | Retry with backoff |

Retry Pattern

from openai import OpenAI, RateLimitError, APIError
import time

def call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            wait = 2 ** attempt
            time.sleep(wait)
        except APIError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
    raise Exception("Max retries exceeded")

---

Platform Differentiators

| Feature | OpenAI | |---------|--------| | Reasoning Effort | Budget-controlled reasoning (none->xhigh) | | Responses API | Next-gen API with CoT passing | | Built-in Tools | web_search, code_interpreter, file_search | | 400K Context | GPT-5.2 largest context window | | Agents SDK | Persistent threads with tool integration | | ChatKit | Official React chat components | | Batch API | 50% cost savings for async processing |

---

Further Reading

For comprehensive coverage, see REFERENCE.md:

• Installation & Configuration: Detailed setup, Azure OpenAI, proxies
• Chat Completions: Complete parameter reference, multi-turn patterns
• Responses API: Full tool integration, streaming events
• Streaming: SSE patterns, tool call streaming
• Tool Calling: Complete loop implementation, Pydantic helpers
• Structured Outputs: JSON Schema mode, Pydantic integration
• Embeddings: Similarity search, vector DB patterns
• Vision & Audio: Multimodal inputs, Whisper, TTS
• Agents SDK: Thread management, multi-agent orchestration
• Batch API: Async processing, cost optimization
• Realtime API: WebSocket audio/video
• ChatKit: React components for chat UIs
• Error Handling: Comprehensive retry patterns
• Rate Limits: Quotas, tier management
• Security: Best practices, API key management

---

Context7 Integration

For up-to-date documentation beyond this skill:

# Python SDK latest
mcp__context7__resolve-library-id(libraryName="openai")
mcp__context7__query-docs(libraryId="/openai/openai-python", query="streaming")

# Node SDK latest
mcp__context7__query-docs(libraryId="/openai/openai-node", query="tool calling")