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

• 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

gpt-5.2

gpt-5.2-pro

gpt-5.1

gpt-5.1-codex

gpt-5

gpt-4o

gpt-4o-mini

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

system

user

assistant

tool

Common Parameters

model

messages

temperature

max_tokens

stream

response_format

tools

reasoning_effort

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

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

text-embedding-3-large

text-embedding-3-small

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

AuthenticationError

RateLimitError

InvalidRequestError

APIConnectionError

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

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")