OpenAI Cookbook — User Guide

OpenAI Cookbook is an official collection of example code, Jupyter notebooks, and articles demonstrating how to use the OpenAI API for real-world tasks. It covers embeddings, chat completions, function calling, fine-tuning, image generation, audio processing, the Agents SDK, Codex, and more — all grounded in runnable, copy-paste-ready code.

1. Quick Start

What You Get

• 80+ Jupyter notebooks covering every major OpenAI API surface: embeddings, chat completions, function calling, fine-tuning, Assistants API, Responses API, DALL-E, Whisper, Realtime API, Agents SDK, and Codex
• Articles on prompt engineering, reliability techniques, and open-source model integration
• Runnable Python scripts including a production-grade parallel API request processor and a sandboxed code migration agent
• Sample datasets (CSV, JSONL, PDF, audio) ready for experimentation
• GPT Actions library with integration recipes for Salesforce, Jira, Confluence, Google Drive, Snowflake, and more

Prerequisites

• Python 3.8+
• An OpenAI API key (set as OPENAI_API_KEY environment variable)
• Jupyter Notebook or JupyterLab (for .ipynb files)

Get Running in 2 Minutes

git clone https://github.com/openai/openai-cookbook.git
cd openai-cookbook
pip install openai tiktoken jupyter
export OPENAI_API_KEY="sk-..."
jupyter notebook

Open any notebook from the examples/ directory and run it cell by cell.

Tip

Start with examples/How_to_format_inputs_to_ChatGPT_models.ipynb if you are new to the OpenAI API — it covers the fundamentals of message formatting and chat completions.

What to Try Next

• Embeddings: examples/Using_embeddings.ipynb — semantic search, clustering, classification
• Function calling: examples/How_to_call_functions_with_chat_models.ipynb — structured tool use
• Fine-tuning: examples/How_to_finetune_chat_models.ipynb — customizing models on your data
• Image generation: examples/Generate_Images_With_GPT_Image.ipynb — creating and editing images
• Agents SDK: examples/agents_sdk/parallel_agents.ipynb — building multi-agent workflows

2. Installation

System Requirements

Clone the Repository

git clone https://github.com/openai/openai-cookbook.git
cd openai-cookbook

Install Core Dependencies

Most notebooks require only the OpenAI Python SDK and a few common libraries:

pip install openai tiktoken jupyter pandas numpy matplotlib

Important

Individual notebooks may require additional packages. Check the import statements at the top of each notebook before running. Some examples include their own requirements.txt files in their subdirectories.

Per-Example Dependencies

Several examples ship their own dependency files:

Install example-specific dependencies:

pip install -r examples/agents_sdk/sandboxed-code-migration/requirements.txt

Verify Installation

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

1.x.x

3. Configuration

API Key Setup

Set your OpenAI API key as an environment variable:

Linux / macOS

export OPENAI_API_KEY="sk-..."

Windows

set OPENAI_API_KEY=sk-...

Python (dotenv)

from dotenv import load_dotenv
load_dotenv()  # reads from .env file

Warning

Never commit your API key to version control. Use environment variables or .env files (add .env to .gitignore).

Additional Environment Variables

Some examples require additional keys beyond OPENAI_API_KEY:

See the Admin Guide for complete configuration reference.

4. Core Usage

Embeddings

The cookbook includes extensive coverage of OpenAI embeddings across multiple use cases.

Getting started with embeddings:

Search and retrieval:

Classification and analysis:

Chat Completions and Prompting

Tip

Use How_to_count_tokens_with_tiktoken.ipynb to estimate costs before running large batch jobs. The tiktoken library lets you count tokens locally without making API calls.

Function Calling

Fine-Tuning

Agents SDK

Build multi-agent systems with the OpenAI Agents SDK:

Note

The Agents SDK examples require the openai-agents package. Install with pip install openai-agents. The sandboxed migration example supports Docker, Cloudflare, and E2B sandbox backends.

Image Generation (DALL-E and GPT Image)

Audio and Speech (Whisper)

Assistants API and File Search

RAG (Retrieval-Augmented Generation)

Realtime API

Codex

Batch Processing and Parallel Requests

The cookbook includes a production-ready parallel API request processor:

python examples/api_request_parallel_processor.py \
  --requests_filepath examples/data/example_requests_to_parallel_process.jsonl \
  --save_filepath results.jsonl \
  --request_url https://api.openai.com/v1/embeddings \
  --max_requests_per_minute 1500 \
  --max_tokens_per_minute 6250000 \
  --token_encoding_name cl100k_base \
  --max_attempts 5 \
  --logging_level 20

Warning

Set --max_requests_per_minute and --max_tokens_per_minute to 50–75% of your actual rate limits to leave headroom. Exceeding limits causes 15-second cooldown pauses.

See also batch_processing.ipynb for using the OpenAI Batch API for high-volume offline processing.

Data Extraction and Transformation

Content Moderation and Safety

Azure OpenAI

Notebooks in examples/azure/ demonstrate the same API patterns using Azure OpenAI Service:

Note

Azure OpenAI uses api-key header authentication instead of Bearer token. The parallel processor script handles this automatically when the request URL contains /deployments.

5. Common Tasks

Run a Notebook Example

1. Navigate to the cookbook directory
2. Start Jupyter: jupyter notebook
3. Open the desired notebook from examples/
4. Set your API key if not already in environment
5. Run cells sequentially (Shift+Enter)

If a cell fails with an import error, install the missing package:

pip install <package-name>

Process Bulk Embeddings

Goal: Embed thousands of text items efficiently without hitting rate limits.

Prerequisites: openai, tiktoken, aiohttp packages installed.

Steps:

1. Prepare a JSONL file with one request per line:

{"model": "text-embedding-3-small", "input": "Your text here", "metadata": {"id": 1}}

2. Run the parallel processor:

python examples/api_request_parallel_processor.py \
  --requests_filepath your_requests.jsonl \
  --request_url https://api.openai.com/v1/embeddings \
  --max_requests_per_minute 1500 \
  --max_tokens_per_minute 6250000

3. Results are saved as JSONL: [{request}, {response}, {metadata}] per line.

Verify: Check the output file has the same number of lines as the input.

If it fails: Check that each line is valid JSON. Use json.dumps() to escape newlines in content.

Run the Sandboxed Code Migration Agent

Goal: Automatically migrate Python code from Chat Completions to the Responses API.

Prerequisites: Docker installed and running, openai-agents package.

Steps:

1. Install dependencies:

cd examples/agents_sdk/sandboxed-code-migration
pip install -r requirements.txt

2. Run on the included fixture repos:

python -m src.run_migration_agent --backend docker

support_reply_service: wrote outputs/support_reply_service/migration.patch and outputs/support_reply_service/migration_report.md
case_summary_service: wrote outputs/case_summary_service/migration.patch and outputs/case_summary_service/migration_report.md

wrote batch summary to outputs/batch_summary.json

3. Run a specific task:

python -m src.run_migration_agent --backend docker --task support_reply_service

Verify: Check outputs/ for migration_report.md, migration.patch, and migration_result.json.

Tip

Use --backend docker for local development (default). Cloudflare and E2B backends are available for cloud-based sandboxing — set the corresponding environment variables first.

Run the Multi-Agent Portfolio Analysis

Goal: Generate an investment analysis memo using a team of AI agents.

Prerequisites: openai-agents, yfinance, fredapi, FRED_API_KEY environment variable.

Steps:

1. Install dependencies:

cd examples/agents_sdk/multi-agent-portfolio-collaboration
pip install -r requirements.txt

2. Open and run multi_agent_portfolio_collaboration.ipynb.

The system orchestrates:

• A Head Portfolio Manager agent that delegates to specialists
• A Fundamental Analysis agent (uses Yahoo Finance MCP + web search)
• A Macro Analysis agent (uses FRED economic data)
• A Quantitative Analysis agent (uses code interpreter)
• A Memo Editor agent that compiles the final report

Verify: Check outputs/ for the generated investment memo and supporting CSVs.

Build a GPT Action for an External Service

Goal: Create a ChatGPT action that connects to an external data source.

The examples/chatgpt/gpt_actions_library/ directory contains integration recipes for:

Each recipe includes authentication setup, OpenAPI spec creation, and testing steps.

Translate a Book with AI

Goal: Translate a LaTeX book between languages preserving formatting.

Steps: Open examples/book_translation/translate_latex_book.ipynb. Sample data in examples/book_translation/data/ includes geometry textbook content in English and Slovenian.

Build a Coding Agent

Goal: Create a code-writing agent with the latest models.

Steps: Open examples/Build_a_coding_agent_with_GPT-5.1.ipynb for a complete walkthrough of building a code-writing agent.

Summarize Long Documents

Goal: Break large documents into chunks and produce coherent summaries.

Steps: Open examples/Summarizing_long_documents.ipynb for chunking strategies and progressive summarization techniques.

Write Unit Tests from Code

Goal: Auto-generate test suites for existing code.

Steps: Open examples/Unit_test_writing_using_a_multi-step_prompt.ipynb for a multi-step prompting approach to test generation.

6. Troubleshooting

Error: openai.AuthenticationError

Cause: Missing or invalid API key.

Solution:

1. Verify your key is set: echo $OPENAI_API_KEY
2. Ensure it starts with sk-
3. Check the key is active in your OpenAI dashboard

Prevention: Use a .env file with python-dotenv to manage keys consistently.

Error: openai.RateLimitError

Cause: Too many requests or tokens per minute.

Solution:

1. Reduce --max_requests_per_minute and --max_tokens_per_minute in the parallel processor
2. Add delays between notebook cells making API calls
3. Use batch processing for non-time-sensitive work

Prevention: Set rate limits to 50–75% of your account's actual limits.

Error: ModuleNotFoundError when running a notebook

Cause: Missing Python package.

Solution:

1. Read the notebook's import cells to identify required packages
2. Check if the example directory has a requirements.txt
3. Install missing packages: pip install <package>

Prevention: Create a virtual environment per example group with all dependencies.

Error: NotImplementedError: API endpoint "..." not implemented in this script

Cause: The parallel processor (api_request_parallel_processor.py) only supports completions, chat/completions, and embeddings endpoints.

Solution: Modify the num_tokens_consumed_from_request() function to add token counting logic for your endpoint, or set a conservative token estimate.

Prevention: Check the supported endpoints before processing.

Error: TypeError: Expecting either string or list of strings for "prompt" field

Cause: The request JSON has an incorrectly typed prompt or input field.

Solution: Ensure prompt (for completions) is a string or list of strings, and input (for embeddings) follows the same pattern.

Error: CLOUDFLARE_SANDBOX_WORKER_URL is required for --backend cloudflare

Cause: Attempting to use Cloudflare sandbox backend without configuration.

Solution:

1. Set CLOUDFLARE_SANDBOX_WORKER_URL environment variable
2. Or switch to Docker: --backend docker

Error: E2B_API_KEY is required for --backend e2b

Cause: Attempting to use E2B sandbox backend without an API key.

Solution:

1. Set E2B_API_KEY environment variable
2. Or switch to Docker: --backend docker

Warning

The sandboxed migration agent requires a running Docker daemon when using --backend docker. Start Docker Desktop or the Docker service before running.

Error: RuntimeError: Migration agent returned no structured output.

Cause: The migration agent completed its run but did not produce a valid MigrationResult output.

Solution:

1. Check the audit log at outputs/<task>/migration_audit.jsonl for tool call details
2. Increase max_turns if the agent ran out of steps
3. Verify the fixture repo's tests pass independently first

Notebooks hang or produce no output

Cause: Large API calls, network issues, or rate limiting.

Solution:

1. Check your internet connection
2. Reduce the size of input data (use smaller sample datasets first)
3. Check the OpenAI status page for outages
4. Try running individual cells instead of "Run All"

Caution

Some notebooks (especially embedding and fine-tuning examples) make many API calls and can incur significant costs. Review the notebook's description and estimated cost before running on large datasets.

GitHub Issue #2608: prompt_cache_retention parameter warning

Cause: Using the prompt_cache_retention parameter that may produce warnings in certain API versions.

Solution: Check the current OpenAI API documentation for supported parameters on the endpoint you are using.

7. FAQ

Q: Which notebook should I start with?

If you are new to the OpenAI API, start with examples/How_to_format_inputs_to_ChatGPT_models.ipynb. For embeddings specifically, begin with examples/Using_embeddings.ipynb. For agents, start with examples/agents_sdk/parallel_agents.ipynb.

Q: Do I need a paid OpenAI account?

Yes. All notebooks make API calls that consume credits. Some notebooks (fine-tuning, large-scale embeddings) can be expensive. Start with smaller examples and sample datasets.

Q: Can I use these examples with Azure OpenAI?

Yes. The examples/azure/ directory contains Azure-specific versions of common patterns. The parallel processor also supports Azure deployment URLs automatically — it detects /deployments in the URL and switches to api-key header authentication.

Q: What models do the examples use?

Examples reference various models. Newer notebooks use gpt-4.1, gpt-5.1, or gpt-5.4. Embedding examples typically use text-embedding-3-small. The sandboxed migration agent defaults to gpt-5.4. Check each notebook's model parameter and update to the latest available model as needed.

Q: How do I use the sample datasets?

Sample data lives in examples/data/. Files include CSVs (fine_food_reviews_1k.csv, AG_news_samples.csv, amazon_furniture_dataset.csv), JSONL files (example_requests_to_parallel_process.jsonl), a SQLite database (Chinook.db), PDFs, and audio files. Notebooks reference these by relative path.

Q: Are the GPT-OSS articles relevant to the OpenAI API?

The articles/gpt-oss/ directory covers running open-source GPT models (fine-tuning with Transformers, local inference via Ollama, LM Studio, vLLM). These are alternatives to the hosted API and use different setup procedures.

Q: How do I validate migration agent output?

Run the eval script:

python examples/agents_sdk/sandboxed-code-migration/evals.py --output-dir outputs/

It checks that patches contain the expected API migration markers (responses.create, output_text) and that tests pass.

Q: What sandbox backends does the migration agent support?

Three backends: docker (default, local), cloudflare (requires CLOUDFLARE_SANDBOX_WORKER_URL), and e2b (requires E2B_API_KEY). Docker is the simplest to set up — just ensure Docker is installed and running.

Q: Can I contribute new examples?

Yes. The repository accepts community contributions. The authors.yaml file maps contributor GitHub usernames to display names and avatars for the cookbook website at cookbook.openai.com.

Q: What are the archive/ directories?

examples/azure/archive/ contains older versions of Azure notebooks that have been superseded by updated versions in the parent directory. They are kept for reference but may use deprecated API patterns.