OpenAI API Development

Sources:

• https://github.com/openai/openai-python (Python SDK)
• https://github.com/openai/openai-cookbook (Examples)
• https://platform.openai.com/docs (Official docs - requires browser access)

This skill provides quick reference for building with the OpenAI API, including the Chat Completions API, Responses API, tool use, and best practices.

Best Practices

API Basics

• Use the official SDKs (openai for Python, openai for Node.js)
• Set reasonable timeouts - Complex tasks may take time
• Handle rate limits - Implement exponential backoff
• Use streaming for better UX on long responses

Model Selection

Chat Completions API

from openai import OpenAI

client = OpenAI()  # Uses OPENAI_API_KEY env var

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

Responses API (New)

The newer Responses API simplifies common patterns:

response = client.responses.create(
    model="gpt-4o",
    instructions="You are a coding assistant.",
    input="How do I reverse a string in Python?"
)
print(response.output_text)

Streaming

stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": prompt}],
    stream=True
)

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

Tool Use (Function Calling)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=tools
)

# Handle tool calls
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    # Execute function and return result...

Vision

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": image_url}}
        ]
    }]
)

Structured Outputs

from pydantic import BaseModel

class Analysis(BaseModel):
    summary: str
    sentiment: str
    confidence: float

response = client.beta.chat.completions.parse(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze: Great product!"}],
    response_format=Analysis
)
result = response.choices[0].message.parsed

Embeddings

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello world"
)
embedding = response.data[0].embedding

Quick Reference

Python SDK

from openai import OpenAI

client = OpenAI()  # Uses OPENAI_API_KEY

# Sync
response = client.chat.completions.create(...)

# Async
from openai import AsyncOpenAI
client = AsyncOpenAI()
response = await client.chat.completions.create(...)

TypeScript SDK

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }]
});

Common Parameters

Environment Variables

OPENAI_API_KEY         # Required API key
OPENAI_ORG_ID          # Organization ID (optional)
OPENAI_BASE_URL        # Custom endpoint (optional)

Error Handling

from openai import APIError, RateLimitError

try:
    response = client.chat.completions.create(...)
except RateLimitError:
    # Implement backoff
    time.sleep(60)
except APIError as e:
    print(f"API error: {e}")

Cost Optimization

• Use gpt-4o-mini for simple tasks (10x cheaper than gpt-4o)
• Set max_tokens appropriately - don't over-allocate
• Use streaming to cancel early when you have enough
• Cache responses for repeated queries
• Batch requests when possible

Documentation Index

Resources synced from official GitHub repositories. Note: platform.openai.com requires browser access.

SDK Reference

Examples & Guides

Official Documentation

For comprehensive API documentation, visit:

• API Reference: https://platform.openai.com/docs/api-reference
• Guides: https://platform.openai.com/docs/guides
• Cookbook: https://cookbook.openai.com

Syncing Documentation

Resources are synced from official OpenAI GitHub repositories:

cd skills/openai-api
bun run scripts/sync-docs.ts