Academy
Optimize All
Sign in
Start learning free

Mastering ChatGPT (OpenAI)The OpenAI API and business integrations · Lesson 16 of 19

The OpenAI API: Responses API fundamentals with working code

Article · 18 min · 9 min lecture

Video lecture

The OpenAI API: Responses API fundamentals with working code

16 chapters · about 9 min · full transcript

Coming soon

Chapter 1 of 16

The OpenAI API

  • Software that uses GPT models
  • Your first working call

The narrated lecture is in production

Every chapter is scripted and ready. Browse the chapters and read the full transcript now — the video will appear here when it’s published.

Chapters

ChatGPT vs the OpenAI API

ChatGPT is an app for people. The OpenAI API lets your software use OpenAI's models: classify every support ticket, generate product descriptions from a catalogue, summarise call notes into your CRM, or power a customer-facing assistant. You create an account on the OpenAI Platform, create a project and an API key, add billing, and pay per use (tokens in and out, priced per model). ChatGPT subscriptions and API billing are separate.

The core building blocks

  • Responses API (client.responses.create): OpenAI's primary API for generating text and using tools. It supports built-in tools (such as web search, file search, code interpreter and remote MCP servers), function calling, structured outputs, images as input, and conversation state (previous_response_id or the Conversations API).
  • Chat Completions API: the previous standard, still supported; you will see it in older tutorials.
  • Models: exact IDs such as gpt-5.5 or newer GPT-6-generation models. Check the models page for current IDs, capabilities and prices; use the smallest model that meets your quality bar.
  • Instructions: system-level guidance (the API equivalent of custom instructions).
  • Reasoning effort: reasoning models accept an effort setting (for example low, medium, high) that trades depth for speed and cost.
  • Structured outputs: constrain output to a JSON schema.
  • Batch API and flex/priority options: process large jobs asynchronously at lower cost, or pay for priority. Check the pricing page for current discounts.

Hands-on: first call in Python

pip install openai
export OPENAI_API_KEY="sk-..."      # from the OpenAI Platform; never commit it
export OPENAI_MODEL="gpt-5.5"       # check the models page for current IDs
import os
import openai
from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from the environment
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.5")

INSTRUCTIONS = (
    "You write product descriptions for Al Waha Dates (premium dates, UAE/UK). "
    "British English. No health claims. Never invent origins, awards or "
    "ingredients; write [TBC] if information is missing."
)

def describe(product: dict) -> str:
    try:
        resp = client.responses.create(
            model=MODEL,
            instructions=INSTRUCTIONS,
            input=f"Write a 60-word description for this product:\n{product}",
        )
    except openai.RateLimitError:
        raise RuntimeError("Rate limited - slow down or retry later")
    except openai.APIStatusError as e:
        raise RuntimeError(f"OpenAI API error {e.status_code}")
    except openai.APIConnectionError:
        raise RuntimeError("Network problem reaching the OpenAI API")
    print("tokens in/out:", resp.usage.input_tokens, resp.usage.output_tokens)
    return resp.output_text

if __name__ == "__main__":
    print(describe({"name": "Medjool Gift Box", "weight": "500g", "origin": "[TBC]"}))

Structured outputs with Pydantic

from typing import Literal
from pydantic import BaseModel

class ReviewTag(BaseModel):
    sentiment: Literal["positive", "neutral", "negative"]
    topic: Literal["delivery", "product", "price", "service", "other"]
    needs_reply: bool
    summary: str

resp = client.responses.parse(
    model=MODEL,
    input=f"Classify this customer review:\n{review_text}",
    text_format=ReviewTag,
)
tag = resp.output_parsed   # a validated ReviewTag instance

Reasoning effort and cost control

For analysis-heavy tasks, set reasoning effort explicitly and measure:

resp = client.responses.create(
    model=MODEL,
    reasoning={"effort": "low"},   # try low/medium/high on your evaluation set
    input="Summarise these call notes into 3 action items: ...",
)

Cost levers: smaller models for simple tasks, lower effort where quality holds, prompt caching of long stable prefixes (automatic for repeated prefixes on supported models; check the docs), and the Batch API for non-urgent bulk work.

Before you launch

  1. Evaluation set: 30 to 100 real examples with expected outputs; rerun on every prompt or model change.
  2. Guardrails: instructions, schemas, and code checks for banned claims or personal data.
  3. Human hand-off for sensitive cases.
  4. Key hygiene: server-side only, per-project keys, least-privilege permissions, rotation on exposure.
  5. Monitoring: usage, cost, latency, errors and quality; set budget alerts and project spend limits in the dashboard.

Worked example: catalogue descriptions for a Gulf retailer

A retailer with 3,000 products needs Arabic and English descriptions. The team tests the prompt on 50 products with a native-speaker reviewer, adds a schema with en and ar fields and a missing_info list, then runs the full catalogue through the Batch API overnight. Items with missing_info go to merchandisers; everything else is spot-checked (5%) before publishing.

Keeping conversation state

For multi-turn assistants, either pass the previous turns back in input, or pass previous_response_id=resp.id so the API continues from the prior response. Store only what you need, and remember that longer histories cost more tokens on every turn.

Pitfalls

  • Calling the API from browser code with a visible key.
  • Confusing ChatGPT plans with API billing.
  • No evaluation set; "vibes-based" launches.
  • Ignoring incomplete responses (check status and handle errors).

How to measure success

Your evaluation accuracy meets an agreed bar, cost per item is known, failures are handled gracefully, and keys are never exposed.

Key takeaways

  • The OpenAI API lets software use OpenAI models; it is billed separately from ChatGPT plans, per token and model.
  • The Responses API is the primary interface (tools, function calling, structured outputs, state); Chat Completions remains supported.
  • Use responses.parse with a Pydantic model for validated JSON; tune model size and reasoning effort; use Batch for bulk work.
  • Launch with an evaluation set, guardrails, human hand-off, server-side keys, spend limits and monitoring.

Check your understanding

Quick questions to lock in the lesson. They don’t count towards your certificate.

  1. A marketer assumes their ChatGPT Plus subscription covers their new app’s API calls. What is correct?
  2. Which approach returns a validated object your code can trust?
  3. Where should an OpenAI API key live in a web app?

Put it into practice

Run the first-call example with your own key on a non-sensitive task, then classify 10 anonymised reviews with the Pydantic schema, checking each by hand and noting any misclassification.

Enrol for free to save your progress

Reading is always free. Enrol to keep your place, take the final assessment and earn a verifiable certificate.