OpenAI Python SDK Tutorial

OpenAI Python SDK: Complete Tutorial

The official OpenAI Python SDK (openai) is the most popular way to interact with the OpenAI API. This guide covers installation, configuration, every major feature, error handling, and advanced patterns for production applications.

Installation

# Install the latest version
pip install openai

# Install with async support
pip install openai httpx

# Verify installation
python -c "import openai; print(openai.__version__)"

Client Initialization

from openai import OpenAI

# Method 1: Explicit configuration
client = OpenAI(
    api_key="sk-your-key",
    base_url="https://claude4u.com/v1"
)

# Method 2: Environment variables (recommended)
# Set OPENAI_API_KEY and OPENAI_BASE_URL in your environment
client = OpenAI()

# Method 3: With custom timeout and retries
client = OpenAI(
    api_key="sk-your-key",
    base_url="https://claude4u.com/v1",
    timeout=60.0,       # 60-second timeout
    max_retries=3        # Retry up to 3 times on transient errors
)

Chat Completions

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a Python expert."},
        {"role": "user", "content": "How do I read a CSV file with pandas?"}
    ],
    temperature=0.7,
    max_tokens=500
)

print(response.choices[0].message.content)
print(f"Tokens used: {response.usage.total_tokens}")

Streaming Responses

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

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

Async Client

from openai import AsyncOpenAI
import asyncio

client = AsyncOpenAI(base_url="https://claude4u.com/v1")

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

asyncio.run(main())

Concurrent Async Requests

async def batch_complete(prompts):
    """Process multiple prompts concurrently."""
    tasks = [
        client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": prompt}]
        )
        for prompt in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return [r.choices[0].message.content for r in responses]

prompts = [
    "Summarize quantum computing in one sentence.",
    "What is machine learning?",
    "Explain API design principles."
]

results = asyncio.run(batch_complete(prompts))
for prompt, result in zip(prompts, results):
    print(f"Q: {prompt}\nA: {result}\n")

JSON Mode / Structured Output

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": "List 3 programming languages as JSON with name and year fields."
    }],
    response_format={"type": "json_object"}
)

import json
data = json.loads(response.choices[0].message.content)
print(json.dumps(data, indent=2))

Function Calling

import json

tools = [{
    "type": "function",
    "function": {
        "name": "get_stock_price",
        "description": "Get the current stock price",
        "parameters": {
            "type": "object",
            "properties": {
                "symbol": {"type": "string", "description": "Stock ticker symbol"}
            },
            "required": ["symbol"]
        }
    }
}]

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

if response.choices[0].message.tool_calls:
    call = response.choices[0].message.tool_calls[0]
    args = json.loads(call.function.arguments)
    print(f"Function: {call.function.name}, Args: {args}")

Embeddings

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Hello world", "How are you?"]
)

for item in response.data:
    print(f"Index {item.index}: {len(item.embedding)} dimensions")

Image Generation

response = client.images.generate(
    model="dall-e-3",
    prompt="A cute robot reading a book in a library",
    size="1024x1024",
    quality="standard",
    n=1
)

print(f"Image URL: {response.data[0].url}")

Error Handling

from openai import (
    OpenAI,
    APIError,
    APIConnectionError,
    RateLimitError,
    AuthenticationError,
    BadRequestError,
    NotFoundError
)

client = OpenAI(base_url="https://claude4u.com/v1")

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}]
    )
except AuthenticationError:
    print("Invalid API key. Check your credentials.")
except RateLimitError:
    print("Rate limit exceeded. Implement backoff or use a relay service.")
except BadRequestError as e:
    print(f"Bad request: {e.message}")
except NotFoundError:
    print("Model not found. Check the model name.")
except APIConnectionError:
    print("Cannot connect to the API. Check your network.")
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")

Custom HTTP Client

import httpx
from openai import OpenAI

# Use a custom HTTP client with proxy
http_client = httpx.Client(
    proxy="http://proxy.example.com:8080",
    timeout=120.0
)

client = OpenAI(
    api_key="sk-your-key",
    base_url="https://claude4u.com/v1",
    http_client=http_client
)

Context Manager Pattern

from openai import OpenAI

with OpenAI(base_url="https://claude4u.com/v1") as client:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)
# HTTP client is automatically closed