Your first API call

Why this is worth thirty minutes even if you are not a programmer

The API is the route where you pay for what you use rather than a flat monthly fee, where you can pin a model version, where you choose the system prompt, and where nothing about the product layer is decided for you. For a light user it is often a tenth of the subscription price. For anyone processing more than a handful of items it is the only sensible route.

You do not need to write software to use it. Free chat front-ends, covered two lessons from now, take a key and give you a chat window. But it helps enormously to see what one request looks like, because then the whole architecture stops being mysterious.

The request

Every major provider accepts something close to this shape. Sign up, create a key in the console, then:

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are terse. British spelling."},
      {"role": "user",   "content": "Three risks of a fixed-price contract."}
    ],
    "temperature": 0.3
  }'

That is the whole thing. A model name, a list of messages with roles, and a couple of settings. In Python:

from openai import OpenAI
client = OpenAI()                      # reads OPENAI_API_KEY from the environment
r = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Summarise this in 40 words: ..."}])
print(r.choices[0].message.content)
print(r.usage)                         # prompt_tokens, completion_tokens

Two things in there matter more than they look. The system role is the layer that consumer products fill in for you and you now control. And r.usage prints exactly what you were charged for, which makes cost concrete rather than theoretical from the first minute.

The convention that makes models interchangeable

That request format started at OpenAI and became a de facto standard. Most providers and nearly every local runner now accept it, which means switching models is often a change of two lines:

client = OpenAI(base_url="https://api.anthropic.com/v1/",  api_key=A_KEY)
client = OpenAI(base_url="https://openrouter.ai/api/v1",   api_key=R_KEY)
client = OpenAI(base_url="http://localhost:11434/v1",      api_key="ollama")

The last line is a model running on your own laptop, answering the same code. This compatibility is the single most valuable thing about the API route, because it makes your work portable in a field where products are withdrawn regularly.

Compatibility is not perfect. Vendor-specific features (thinking budgets, caching controls, certain tool formats) usually need that vendor’s own library. The common path works everywhere; the interesting features do not.

Reading the response

The reply comes back as JSON, and three fields in it are worth knowing by name. choices[0].message.content is the answer. usage is the token counts you were billed for. And finish_reason tells you why the model stopped: stop means it finished naturally, length means it hit the maximum output you allowed and was cut off mid-sentence.

That last one explains a complaint people bring to support constantly: answers that end halfway through a word. It is almost never the model failing; it is a max_tokens setting somewhere, either yours or the front-end’s default. Raise it, or ask for a shorter answer, and the truncation goes away.

What it does not give you

Be clear about what you are giving up, because people are sold the API as strictly better and it is not.

• No memory. Every request is independent. A conversation exists only because you resend the previous messages, and you pay for them again each turn.
• No web search, no file store, no code sandbox, unless you add them.
• No mobile app, no support, no history.
• A bill instead of a price. Which is the next lesson, and it is the one that goes wrong.

Getting started for nothing

Most providers give new accounts free credits, typically $5 to $10, and some free tiers on developer platforms are generous enough for real personal use. Several hosted providers of open models offer free tiers as well. Between them you can do this whole module without paying anything.

The condition is the usual one: free tiers frequently permit the provider to use your inputs to improve the service, where the paid API generally does not. If you are experimenting with your own text, that is a fair trade. If you are experimenting with a client’s contract, it is not.