{"id":65803,"date":"2026-01-30T03:51:23","date_gmt":"2026-01-30T03:51:23","guid":{"rendered":"https:\/\/www.askpython.com\/?p=65803"},"modified":"2026-04-16T03:48:00","modified_gmt":"2026-04-16T03:48:00","slug":"openai-python-sdk-developer-guide","status":"publish","type":"post","link":"https:\/\/www.askpython.com\/python\/examples\/openai-python-sdk-developer-guide","title":{"rendered":"OpenAI Python SDK: Complete Developer Guide (2026)"},"content":{"rendered":"

Want to add ChatGPT, image generation, and AI capabilities to your Python apps? The OpenAI Python SDK makes this straightforward. In this guide, you’ll build AI-powered features-from chat interfaces to semantic search-using Python 3.13 and the latest SDK patterns.<\/p>\n

What you’ll learn<\/strong>: Chat completions with streaming responses, function calling for API integration, embeddings for semantic search, vision analysis, and production deployment with proper error handling. All code is ready to copy and run.<\/p>\n

Quick heads-up<\/strong>: If you’re using old code with openai.ChatCompletion.create()<\/code>, that pattern broke in November 2023 when version 1.0 launched. The SDK now uses client instances, which is actually cleaner once you see it in action. Don’t worry-I’ll show you the new patterns step by step.<\/p>\n

Quick start: Your first AI-powered response in 5 minutes<\/h2>\n

Let’s get you making AI requests right away. Install the SDK and make your first API call.<\/p>\n

Install the SDK<\/strong>:<\/p>\n

\n
\npip3 install openai\n<\/pre>\n<\/div>\n
The package works with Python 3.13 or higher. If you’re on an older version, this is a good time to upgrade!<\/p>\n
Get your API key<\/strong>: Head to platform.openai.com\/api-keys<\/a> and create a new key. Store it as an environment variable (never hardcode it in your source files-trust me, you’ll thank yourself later):<\/p>\n
\n
\nexport OPENAI_API_KEY='sk-proj-...'\n<\/pre>\n<\/div>\n
Make your first request<\/strong>:<\/p>\n
\n
\nfrom openai import OpenAI\nimport os\n\n# Create a client instance (reuse this, don't create per request)\nclient = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))\n\n# Let's talk to GPT!\nresponse = client.chat.completions.create(\n    model="gpt-5-mini",\n    messages=[{"role": "user", "content": "Hello!"}]\n)\n\nprint(response.choices[0].message.content)\n# Output: "Hello! How can I help you today?"\n<\/pre>\n<\/div>\n
🎉 Nice work!<\/strong> You just made your first AI request. The client handles authentication, retries, and connection pooling automatically-one less thing to worry about.<\/p>\n
Pro tip<\/strong>: Create one client instance per application and reuse it. The SDK uses connection pooling internally, which significantly improves performance.<\/p>\n
For async applications (FastAPI, asyncio), use the async client:<\/p>\n
\n
\nfrom openai import AsyncOpenAI\n\nasync_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))\n\nasync def get_completion(prompt):\n    response = await async_client.chat.completions.create(\n        model="gpt-5-mini",\n        messages=[{"role": "user", "content": prompt}]\n    )\n    return response.choices[0].message.content\n<\/pre>\n<\/div>\n
Building conversations with chat completions<\/h2>\n
Chat completions power everything from customer support bots to code generation tools. You send a list of messages (think of it as the conversation history), and the API returns the model’s response. Let’s explore how this works.<\/p>\n
Understanding message roles<\/h3>\n
The messages array is like a conversation transcript. Each message has a role<\/code> (who’s speaking) and content<\/code> (what they said). The model reads this entire conversation to understand context and generate relevant responses.<\/p>\n
System messages<\/strong> set the assistant’s behavior. They define personality, constraints, and output format. The model treats system messages as instructions that override default behavior.<\/p>\n
\n
\nmessages = [\n    {"role": "system", "content": "You are a Python expert who explains concepts concisely with code examples."},\n    {"role": "user", "content": "What are Python decorators?"}\n]\n<\/pre>\n<\/div>\n
User messages<\/strong> represent input from the person using your application. These are questions, commands, or prompts.<\/p>\n
Assistant messages<\/strong> store the model’s previous responses. Include them to maintain conversation context across multiple turns.<\/p>\n
\n
\nmessages = [\n    {"role": "system", "content": "You are a helpful assistant."},\n    {"role": "user", "content": "What is RAG?"},\n    {"role": "assistant", "content": "RAG (Retrieval Augmented Generation) combines information retrieval with text generation..."},\n    {"role": "user", "content": "How do I implement it in Python?"}\n]\n<\/pre>\n<\/div>\n
The model sees the entire message history and generates a response based on all context. This enables multi-turn conversations where the assistant remembers previous exchanges.<\/p>\n
Model parameters<\/h3>\n
Control model behavior with parameters. These affect creativity, response length, and output diversity.<\/p>\n
temperature<\/strong> (0.0-2.0) controls randomness. Lower values (0.0-0.3) produce deterministic, focused responses. Higher values (0.7-1.5) increase creativity and variation. Use low temperature for factual tasks (code generation, data extraction) and higher temperature for creative tasks (brainstorming, storytelling).<\/p>\n
\n
\n# Deterministic code generation\nresponse = client.chat.completions.create(\n    model="gpt-5",\n    messages=[{"role": "user", "content": "Write a Python function to calculate fibonacci"}],\n    temperature=0.1\n)\n\n# Creative writing\nresponse = client.chat.completions.create(\n    model="gpt-5",\n    messages=[{"role": "user", "content": "Write a sci-fi story opening"}],\n    temperature=1.2\n)\n<\/pre>\n<\/div>\n
max_tokens<\/strong> limits response length. The model stops generating after reaching this limit. Count both input and output tokens against context window limits. GPT-5.2 supports 200k tokens, GPT-5 supports 128k tokens.<\/p>\n
top_p<\/strong> (0.0-1.0) implements nucleus sampling. The model considers only the top P probability mass of tokens. Use top_p=0.1<\/code> for focused responses or top_p=0.9<\/code> for diverse outputs. Don’t adjust both temperature and top_p simultaneously.<\/p>\n
presence_penalty<\/strong> (-2.0 to 2.0) reduces repetition of topics. Positive values penalize tokens that already appeared, encouraging the model to explore new topics.<\/p>\n
frequency_penalty<\/strong> (-2.0 to 2.0) reduces repetition of specific tokens. Positive values penalize tokens based on their frequency in the output, discouraging verbatim repetition.<\/p>\n
\n
\nresponse = client.chat.completions.create(\n    model="gpt-5",\n    messages=[{"role": "user", "content": "Explain Python async\/await"}],\n    temperature=0.7,\n    max_tokens=500,\n    presence_penalty=0.6,\n    frequency_penalty=0.3\n)\n<\/pre>\n<\/div>\n
Streaming responses<\/h3>\n
Streaming sends response tokens as they’re generated instead of waiting for completion. This improves perceived latency in user-facing applications. Users see text appearing progressively rather than waiting 5-10 seconds for a full response.<\/p>\n
Enable streaming with stream=True<\/code>. The API returns an iterator of chunk objects. Each chunk contains a delta with new content.<\/p>\n
\n
\nresponse = client.chat.completions.create(\n    model="gpt-5",\n    messages=[{"role": "user", "content": "Explain RAG in detail"}],\n    stream=True\n)\n\nfor chunk in response:\n    if chunk.choices[0].delta.content:\n        print(chunk.choices[0].delta.content, end="", flush=True)\n<\/pre>\n<\/div>\n
The streaming response yields ChatCompletionChunk<\/code> objects. Access content via chunk.choices[0].delta.content<\/code>. The first chunk often has empty content, and the final chunk signals completion with finish_reason<\/code>.<\/p>\n
Handle streaming errors carefully. Network failures mid-stream leave partial responses. Wrap streaming in try\/except and implement retry logic.<\/p>\n
\n
\ndef stream_completion(prompt):\n    try:\n        response = client.chat.completions.create(\n            model="gpt-5",\n            messages=[{"role": "user", "content": prompt}],\n            stream=True,\n            timeout=30\n        )\n        \n        full_response = ""\n        for chunk in response:\n            if chunk.choices[0].delta.content:\n                content = chunk.choices[0].delta.content\n                print(content, end="", flush=True)\n                full_response += content\n        \n        return full_response\n    except Exception as e:\n        print(f"\\nStreaming error: {e}")\n        return None\n<\/pre>\n<\/div>\n
Model comparison<\/h3>\n
Choose models based on task complexity, latency requirements, and budget. GPT-5.2 excels at complex reasoning but costs more. GPT-5-mini handles simple tasks at 1\/10th the cost.<\/p>\n
\n\n\n\n\n\n\n\n
Model<\/th>\nCost (1M tokens input\/output)<\/th>\nContext Window<\/th>\nSpeed<\/th>\nUse Case<\/th>\n<\/tr>\n<\/thead>\n
GPT-5.2<\/td>\n$8\/$24<\/td>\n200k<\/td>\nMedium<\/td>\nComplex reasoning, research, analysis<\/td>\n<\/tr>\n
GPT-5<\/td>\n$3\/$9<\/td>\n128k<\/td>\nFast<\/td>\nGeneral tasks, content generation<\/td>\n<\/tr>\n
GPT-5-mini<\/td>\n$0.30\/$0.90<\/td>\n64k<\/td>\nFastest<\/td>\nSimple tasks, high-volume processing<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
GPT-5.2 outperforms GPT-5 on benchmarks requiring multi-step reasoning (GPQA, MATH, HumanEval). For tasks like classification, summarization, or simple Q&A, GPT-5-mini provides 90% of the quality at 10% of the cost.<\/p>\n
Test your specific use case with all three models. Measure quality (human eval or automated metrics) and cost. Many applications can use GPT-5-mini for 80% of requests and route complex queries to GPT-5.2.<\/p>\n
Function calling and tool integration<\/h2>\n
Function calling lets the model decide when to call external functions. Instead of generating text, the model outputs structured JSON with function names and arguments. Your code executes the function and returns results to the model, which incorporates them into the response.<\/p>\n
This enables API integration, database queries, calculations, and external tool usage. The model determines which function to call based on the user’s request and available tools.<\/p>\n
What is function calling?<\/h3>\n
Function calling solves the problem of structured output and external data access. Without it, you’d need to parse unstructured text to extract API calls or database queries. Function calling provides a structured interface.<\/p>\n
The workflow:<\/p>\n
    \n
  1. Define available functions with JSON schemas<\/li>\n
  2. Send user message with function definitions<\/li>\n
  3. Model returns function call (if needed) or text response<\/li>\n
  4. Execute function with provided arguments<\/li>\n
  5. Send function result back to model<\/li>\n
  6. Model generates final response using function output<\/li>\n<\/ol>\n
    Use cases include weather APIs, database lookups, calculator functions, web searches, and any external data source the model needs to access.<\/p>\n
    Tool definitions<\/h3>\n
    Define functions using JSON schemas. Each function needs a name, description, and parameter specification. The model uses descriptions to decide when to call functions.<\/p>\n
    \n
    \ntools = [\n    {\n        "type": "function",\n        "function": {\n            "name": "get_weather",\n            "description": "Get current weather for a location. Use this when users ask about weather conditions.",\n            "parameters": {\n                "type": "object",\n                "properties": {\n                    "location": {\n                        "type": "string",\n                        "description": "City name or coordinates (e.g., 'San Francisco' or '37.7749,-122.4194')"\n                    },\n                    "unit": {\n                        "type": "string",\n                        "enum": ["celsius", "fahrenheit"],\n                        "description": "Temperature unit"\n                    }\n                },\n                "required": ["location"]\n            }\n        }\n    },\n    {\n        "type": "function",\n        "function": {\n            "name": "calculate",\n            "description": "Perform mathematical calculations. Use for arithmetic operations.",\n            "parameters": {\n                "type": "object",\n                "properties": {\n                    "expression": {\n                        "type": "string",\n                        "description": "Mathematical expression to evaluate (e.g., '2 + 2' or 'sqrt(16)')"\n                    }\n                },\n                "required": ["expression"]\n            }\n        }\n    }\n]\n<\/pre>\n<\/div>\n
    Write clear descriptions. The model uses them to decide which function matches the user’s intent. Specify parameter types, constraints (enums), and whether parameters are required.<\/p>\n
    Parallel function calls<\/h3>\n
    The model can call multiple functions in a single request. This reduces latency when multiple operations are independent.<\/p>\n
    \n
    \nimport json\n\ndef get_weather(location, unit="celsius"):\n    # Simulate API call\n    return {"temperature": 22, "condition": "sunny", "unit": unit}\n\ndef calculate(expression):\n    # Safe eval for demo - use a proper parser in production\n    try:\n        result = eval(expression)\n        return {"result": result}\n    except:\n        return {"error": "Invalid expression"}\n\n# User asks: "What's the weather in Tokyo and what's 15 * 24?"\nresponse = client.chat.completions.create(\n    model="gpt-5",\n    messages=[{"role": "user", "content": "What's the weather in Tokyo and what's 15 * 24?"}],\n    tools=tools\n)\n\n# Model returns multiple tool calls\ntool_calls = response.choices[0].message.tool_calls\n\nif tool_calls:\n    # Execute all function calls\n    messages = [{"role": "user", "content": "What's the weather in Tokyo and what's 15 * 24?"}]\n    messages.append(response.choices[0].message)\n    \n    for tool_call in tool_calls:\n        function_name = tool_call.function.name\n        arguments = json.loads(tool_call.function.arguments)\n        \n        if function_name == "get_weather":\n            result = get_weather(**arguments)\n        elif function_name == "calculate":\n            result = calculate(**arguments)\n        \n        messages.append({\n            "role": "tool",\n            "tool_call_id": tool_call.id,\n            "content": json.dumps(result)\n        })\n    \n    # Get final response with function results\n    final_response = client.chat.completions.create(\n        model="gpt-5",\n        messages=messages\n    )\n    \n    print(final_response.choices[0].message.content)\n    # Output: "The weather in Tokyo is 22\u00b0C and sunny. 15 * 24 equals 360."\n<\/pre>\n<\/div>\n
    The model executes both function calls in parallel (conceptually). Your code runs them and returns results. The model then generates a natural language response incorporating both answers.<\/p>\n
    Tool choice control<\/h3>\n
    Control whether the model must call functions or can respond with text. The tool_choice<\/code> parameter accepts:<\/p>\n