Topolearn

Learn OpenAI API

Build with OpenAI models through the Responses API and the openai Python SDK

25 lessons · 5 hours · 4 levels · covers OpenAI API as of Oct 2026 (Responses API, openai Python SDK, openai-agents 0.24)

The OpenAI API gives programs access to OpenAI's models for text, reasoning, images, embeddings and audio. The recommended interface is the Responses API, used through the official Python SDK `openai`, with built-in tools such as web search, file search and code interpreter, function calling, structured outputs, batch processing and the open-source Agents SDK for building agents.

Sign in free to track progressOfficial docs ↗

Before you start

OpenAI API builds on these; the tree links to the exact lessons you need.

PythonPractical levelAI & LLM fundamentalsPractical level

How deep do you want to go?

1. EssentialsRead and write simple code, do the everyday basics8 lessons · 1 hour in total
2. PracticalUse it productively at work, with the usual idioms15 lessons · 3 hours in total
3. AdvancedThe less common features, performance and trade-offs21 lessons · 4 hours in total
4. ExpertInternals and the edge cases experts know25 lessons · 5 hours in total

The OpenAI API tree

OpenAI APIThe OpenAI API platformThe OpenAI APIplatformAPI key and Python SDK setupAPI key and PythonSDK setupYour first Responses API callYour first ResponsesAPI callInstructions and message rolesInstructions andmessage rolesOutput items, status and usageOutput items, statusand usageConversation stateConversation stateStreaming responsesStreaming responsesChoosing an OpenAI modelChoosing an OpenAImodelStructured outputs (JSON)Structured outputs(JSON)Function callingFunction callingBuilt-in tools: web search and codeBuilt-in tools: websearch and codeEmbeddingsEmbeddingsFile search and vector storesFile search andvector storesImages: vision input and generationImages: vision inputand generationErrors, retries and timeoutsErrors, retries andtimeoutsCalling a model through an APICalling a modelthrough an APIVirtual environments and pipVirtual environmentsand pipPrompts, messages and rolesPrompts, messagesand rolesSystem prompts and instructionsSystem prompts andinstructionsTokensTokensThe context windowThe context windowStructured output (JSON)Structured output(JSON)Classes and instancesClasses andinstancesTool calling (function calling)Tool calling (functioncalling)Embeddings and semantic similarityEmbeddings andsemantic similarityRetrieval-augmented generation (RAG)Retrieval-augmentedgeneration (RAG)Exceptions in depthExceptions in depth
Essentials and Practical shown (15 of 25 lessons); the full list is below. Click a lesson to read it.

All 25 lessons, in order

Getting started

  1. The OpenAI API platform · Essentials · 8 min

    What the OpenAI API offers, why the Responses API is the recommended starting point, and what was retired.

  2. API key and Python SDK setup · Essentials · 8 min

    Create a project API key, store it in OPENAI_API_KEY, and install the openai package.

  3. Choosing an OpenAI model · Essentials · 8 min

    Compare the current model families by capability, speed and cost, and keep up with deprecations.

The Responses API

  1. Your first Responses API call · Essentials · 9 min

    Call client.responses.create with a model and input, and read the answer with output_text.

  2. Instructions and message roles · Essentials · 8 min

    Give stable guidance with instructions, and send input as a list of role-tagged messages.

  3. Output items, status and usage · Essentials · 9 min

    Read the typed items in response.output, check status for incomplete answers, and track tokens in usage.

  4. Conversation state · Essentials · 11 min

    Keep multi-turn context by resending history, chaining previous_response_id, or using the Conversations API.

  5. Streaming responses · Essentials · 8 min

    Set stream=True and handle events such as response.output_text.delta to show text as it is generated.

Tools and structured output

  1. Structured outputs (JSON) · Practical · 12 min

    Make replies follow a JSON Schema with text.format, or parse them straight into a Pydantic model with responses.parse.

  2. Function calling · Practical · 15 min

    Describe your functions as tools, run the function_call items the model returns, and send back function_call_output.

  3. Built-in tools: web search and code · Practical · 11 min

    Turn on OpenAI-hosted tools such as web_search and code_interpreter with one entry in tools.

  4. File search and vector stores · Practical · 13 min

    Upload documents to a vector store and let the hosted file_search tool retrieve relevant passages with citations.

  5. Reasoning effort and reasoning items · Advanced · 12 min

    Tune how hard the model thinks with reasoning.effort, read reasoning summaries, and budget for hidden reasoning tokens.

  6. Remote MCP servers and approvals · Advanced · 12 min

    Connect a remote MCP server as a tool, restrict which of its tools are allowed, and approve calls before they run.

Embeddings, images and audio

  1. Embeddings · Practical · 10 min

    Turn text into vectors with client.embeddings.create and compare them with cosine similarity for search.

  2. Images: vision input and generation · Practical · 11 min

    Send images as input_image parts for the model to read, and know the options for generating images.

  3. Audio and the Realtime API · Advanced · 10 min

    Know the options for speech: transcription, text-to-speech, and low-latency voice conversations with the Realtime API.

Production and cost

  1. Errors, retries and timeouts · Practical · 11 min

    Catch the SDK's typed exceptions, use its built-in retries, and tune timeouts for your app.

  2. Prompt caching and flex processing · Advanced · 11 min

    Get automatic cache discounts by keeping prompt prefixes stable, and use service_tier="flex" for cheaper non-urgent calls.

  3. The Batch API · Advanced · 12 min

    Run large jobs asynchronously from a JSONL file, get results within 24 hours, and pay about half price.

  4. Rate limits and usage tiers · Advanced · 10 min

    Understand RPM and TPM limits, usage tiers and rate-limit headers, and back off with jitter when you hit them.

  5. Controlling cost and latency · Expert · 12 min

    Combine model choice, reasoning effort, output length, caching, Batch and flex into a measured cost strategy.

Agents

  1. The OpenAI Agents SDK · Expert · 15 min

    Build agents with Agent, Runner, tools, handoffs and sessions, and know when to use the Agents API instead.

Quality and safety

  1. Moderation, guardrails and safety · Expert · 14 min

    Screen content with the free moderation endpoint, add agent guardrails, defend against prompt injection and identify end users.

  2. Evaluating OpenAI apps · Expert · 14 min

    Define success criteria, build a test set, grade with code or a model, and note that OpenAI's hosted Evals platform is being retired.