+190 XP

ChatGPT · The API: your first real calls

The fastest way to outgrow the ChatGPT window is to make the same model answer from inside your own code, and with OpenAI that takes about ten lines. This lesson covers those ten lines: what is OpenAI-specific, why the Responses API is now the default, and how to stream tokens as they arrive.

Set up once, then forget it

Get a key from the API keys page. Treat it like a password: it is tied to billing, and anyone holding it can spend your credits. Never paste it into code or commit it to git.

Set it as an environment variable so the SDK finds it automatically:

bash
export OPENAI_API_KEY="sk-proj-..."
pip install openai

The official Python SDK reads OPENAI_API_KEY on its own, so you never write the key in your script. One boundary matters here: your API account and your ChatGPT subscription are separate. ChatGPT Plus or Pro does not give you API credits, and API usage is billed per token against a different balance. They share models, not wallets.

Your first real call

Here is a complete, runnable script using the Responses API, OpenAI's current primary interface:

python
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5-mini",
    instructions="You are a terse assistant. Answer in one sentence.",
    input="Explain what an idempotent API request is.",
)

print(response.output_text)

Run it and you get a single clean sentence back. Now for the parts that are specific to OpenAI.

client = OpenAI()

This builds the client and silently picks up your environment key. Everything you do flows through this object: text generation, embeddings, files, audio. You configure it once.

model="gpt-5-mini"

The model string is a real, billable choice, not a label. The current family is GPT-5, which launched in August 2025 and has been updated with point releases since (GPT-5.1 in November 2025, GPT-5.2 in December 2025). In practice you pick a tier: the latest full flagship (for example gpt-5.2) for the hardest work, gpt-5-mini as the everyday workhorse, and gpt-5-nano for cheap, high-volume calls. A classifier or a formatter wants nano. A support bot is usually fine on mini. A multi-step planning task can justify the flagship.

You will still see older names in tutorials: the GPT-4.1 line and the o-series reasoning models such as o3 and o4-mini. They worked as separate families. GPT-5 folds reasoning into one line, so you no longer switch model families to get a model that thinks before answering. Check the current roster and pricing on the models page, because the lineup keeps moving and new point releases arrive every few months.

Reasoning effort

GPT-5 models reason before they answer, and you control how much with one parameter:

python
response = client.responses.create(
    model="gpt-5-mini",
    reasoning={"effort": "low"},
    input="Classify this email as billing, bug, or other: 'I was charged twice.'",
)

Lower effort is faster and cheaper. Higher effort helps on math, code and multi-step planning. For simple extraction or classification, start low and raise it only if quality drops. The exact effort levels supported vary a little between models, so check the model page if a value is rejected.

instructions vs input

This is the cleanest improvement the Responses API brings. instructions holds the system-level steering (persona, rules, output format). input is the actual user turn. You no longer hand-build a list of role-tagged message dictionaries for simple calls. For a single exchange, two strings is all you need.

response.output_text

A convenience accessor that flattens the response into the final text string. The full response object carries more: token usage, the model that actually served you, tool calls, and structured content blocks. For quick work, output_text is what you want. For production, you will read the richer fields.

Responses or chat completions?

You will see both in tutorials, so know the difference.

Chat Completions (client.chat.completions.create) is the older, widely copied interface. It takes a messages list of {"role": ..., "content": ...} dicts. It still works and is not deprecated, so existing code is safe.

Responses (client.responses.create) is what OpenAI recommends for new projects. It can keep conversation state for you, has built-in tools (web search, file search, code interpreter) you can switch on without wiring them yourself, and handles multi-step tool use more cleanly. The Responses API docs are the canonical reference.

A third name shows up in older guides: the Assistants API. OpenAI deprecated it in favour of Responses and shut it down on 26 August 2026. Tutorials built on it no longer run. If you inherit Assistants code, port it to Responses (threads map to conversations, assistants map to reusable prompts plus tools).

Rule of thumb: new code, start with Responses. Reach for Chat Completions only if you are extending something that already uses it.

Streaming: tokens as they arrive

Waiting for a long answer to fully generate before showing anything feels broken to users. Streaming sends tokens as the model produces them, which gives you the typewriter effect you see in ChatGPT.

You opt in with stream=True and iterate over events:

python
from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="gpt-5-mini",
    input="Write a two-line haiku about slow APIs.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
print()

The stream yields typed events, not just raw text. You filter for response.output_text.delta to catch the incremental text chunks. Other event types announce when the response starts, when a tool is called, and when generation completes. The flush=True forces each chunk to the terminal immediately instead of buffering.

With reasoning models there can be a short pause before the first text token while the model thinks. Lower reasoning effort shortens it.

Streaming changes nothing about cost or the final result. It only changes *when* you see the bytes. Use it for any user-facing interface and skip it for batch jobs where nobody is watching.

Three OpenAI-specific things worth knowing early

Structured Outputs

When you need the model to return data your code can parse, do not beg it for JSON in the prompt and hope. Use Structured Outputs, which forces the response to match a schema you define. You pass a JSON Schema (or a Pydantic model in Python) and OpenAI guarantees the shape, so you never write defensive parsing for a stray markdown fence again.

python
from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class Ticket(BaseModel):
    priority: str
    summary: str

response = client.responses.parse(
    model="gpt-5-mini",
    input="My checkout button has been broken for two days, losing sales.",
    text_format=Ticket,
)

ticket = response.output_parsed
print(ticket.priority, "|", ticket.summary)

response.output_parsed hands you a typed Ticket object. For anyone building real features, this is the single biggest reliability upgrade. The Structured Outputs guide covers the schema rules.

Function calling

The model can decide to call functions you expose, returning the function name and arguments for you to execute. You describe your functions, the model picks one when relevant, you run it, then you feed the result back. Tool-using assistants are built on this primitive. Note the boundary: the API's function calling is not the same as GPT Actions in Custom GPTs. Actions are the no-code version inside the ChatGPT product. Function calling is the raw mechanism you control in code.

OpenAI Function Calling Explained

Watch on YouTube

The agents SDK

When one function call becomes a loop of planning, calling tools, and checking results, move up to the Agents SDK. It is OpenAI's official framework for multi-step agents: it manages the tool-call loop, handoffs between specialized agents, and guardrails, so you do not hand-roll the orchestration. You do not need it for your first calls. Once a single Responses call is not enough, it is the natural next step, and it builds directly on the Responses API.

Knowledge check

1. Why should you set your OpenAI key as an environment variable rather than writing it directly in your script?

2. A colleague argues that their ChatGPT Plus subscription should cover their API usage. What is the correct clarification?

3. You need to build a fast, cheap text classifier that just labels incoming messages. Which model choice best fits the job?

MULTIPLE CHOICE

4. Select ALL correct statements about the Responses API and the OpenAI client as described in the lesson.

Select all the correct answers.

MULTIPLE CHOICE

5. Select ALL correct statements about the distinction between 'instructions' and 'input' in the Responses API.

Select all the correct answers.

Reading the response object properly

For anything beyond a demo, stop printing output_text and start inspecting the whole object. Two fields matter immediately.

Usage. Every response reports token counts:

python
print(response.usage.input_tokens, response.usage.output_tokens)
print(response.usage.output_tokens_details.reasoning_tokens)

This is how you measure cost. Input tokens (your prompt and instructions) and output tokens (the generation) are priced differently, and output is usually the more expensive side. The reasoning tokens a GPT-5 model spends thinking are billed as output even though you never see them, so a short answer can still cost more than you expect. Logging usage from day one saves you from a surprise bill.

The served model. The model field tells you which exact model version answered. When you pin a dated snapshot versus an alias that auto-updates, this field is how you confirm what ran. For reproducible production behavior, pin a specific snapshot rather than a floating alias. With point releases arriving every few months, this matters more than it used to.

Errors you will actually hit

Real calls fail for real reasons. Handle the common ones explicitly:

python
from openai import OpenAI, RateLimitError, APIError

client = OpenAI()

try:
    response = client.responses.create(
        model="gpt-5-mini",
        input="Summarize the API economy in one line.",
    )
    print(response.output_text)
except RateLimitError:
    print("Slow down or upgrade your tier, then retry with backoff.")
except APIError as err:
    print(f"OpenAI-side issue: {err}")

RateLimitError is the one beginners meet first. New API accounts start on a low usage tier with modest per-minute limits, and tiers rise automatically as your account ages and you spend. Do not treat a rate limit as a bug. Treat it as a signal to add retry with backoff, which the SDK can do for you via the max_retries setting on the client. APIError and its subclasses cover authentication, bad requests, and transient server errors. Catch them so one hiccup does not crash your app.

Keep latency and cost sane

A few habits pay off immediately:

  • Cap output with max_output_tokens so a chatty model cannot run long and run up the bill. On reasoning models the cap includes the hidden reasoning tokens, so leave headroom: a cap that is too tight can end the response before any visible text appears.
  • Right-size the model and the effort. Most production traffic runs fine on gpt-5-mini or gpt-5-nano with low reasoning effort. Save the flagship and high effort for tasks that need them.
  • Stream user-facing calls, and send independent background calls concurrently rather than in a slow loop. Perceived speed comes from streaming, real throughput from concurrency.

Those levers (output cap, model and effort, concurrency) cover most of the cost and latency tuning you will do early on.

Key Takeaways

  • Start new code on the Responses API (client.responses.create) with instructions and input. Keep Chat Completions for existing codebases. The Assistants API was shut down in August 2026, so port any old Assistants code to Responses.
  • Default to the GPT-5 family (gpt-5-mini is a sensible start, the latest GPT-5.x flagship for hard work) and tune the reasoning effort instead of switching to a separate reasoning model.
  • Set OPENAI_API_KEY as an environment variable and remember your API balance is separate from any ChatGPT subscription.
  • Use Structured Outputs (responses.parse with a Pydantic model) whenever you need parseable data, instead of prompting for JSON and hoping.
  • Read response.usage, including reasoning tokens, from day one, and set max_output_tokens with enough headroom.
  • Stream user-facing interfaces by filtering response.output_text.delta events, and catch RateLimitError with backoff rather than letting it crash your app.

What to do, from this lesson

These actions are compiled in the role's Playbook.

  • Start new code on the Responses API and read response.usage from day one
See the full action playbook →