AI engineering / Core / 02.03
Model APIs side by side
The same question sent to Claude, OpenAI and Gemini: what every call shares, where the shapes differ, and how to read each reply.
14 min readFree
One question, three doors
The last lesson, Open-weight model families, ended with a promise: next, model APIs side by side, the same call in different shapes. Here it is.
Think of three restaurants. You want the same soup in each. In every one you give your name, say what you want, and wait. But each has its own menu card, its own way of taking orders and its own bill. Model APIs are like that. The idea is the same everywhere. The details change from door to door.
An API (application programming interface) is a set of rules for one program to talk to another over the internet. Here, your program sends a question to a model that runs on someone else's computers, and gets an answer back. That one trip is a call.
By the end you will know what every call has in common, where three vendors differ, how to keep your key safe, which errors to expect, and you will run a small program that turns three different replies into one tidy record.
Key words
- Endpoint
- The web address your program sends the call to.
- API key
- A secret password string that tells the vendor who is calling, and who to bill.
- Header
- A small label sent along with the call, such as the one that carries your key.
- Request body
- The main content of the call: the model name, your question and your settings, written as JSON (a text format of labels and values).
- Environment variable
- A named value kept by your computer, outside your code, that a program can read at run time.
- Stop reason
- The model's note on why it stopped writing, for example it finished, or it ran out of room.
- Rate limit
- A cap on how many calls you may send in a short time.
Three real requests
Below are real examples copied from each vendor's own docs. They are shown for reading only. They are not run here, because running them needs a key and costs money. The model names in them are the ones the docs print on the day we checked, and they will age. Always take the current name from the vendor's docs.
Claude: the Messages API
Anthropic's call goes to one address, /v1/messages. The key goes in a header named x-api-key. A second header, anthropic-version, names the version of the API you expect. The body has a model, a max_tokens, and a list of messages. Each message has a role, here "user", and its content.
# From the Claude "Get started" docs, shown without its output (not run here)
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1000,
"messages": [
{
"role": "user",
"content": "What should I search for to find the latest developments in renewable energy?"
}
]
}'The docs call max_tokens "The maximum number of tokens to generate before stopping." They add that the model may stop before it gets there. Here max_tokens is required: the call has to say how much room the model gets.
OpenAI: the Responses API
OpenAI's call goes to /v1/responses. The key goes in an Authorization header, in the form "Bearer" and then the key. The body has a model and an input. The input can be one plain string, as in the snippet below, or a list of items. In the docs' list example, each item has a role and a content list of parts, and a part looks like {"type": "input_text", "text": ...}.
# From the OpenAI developer quickstart, shown without its output (not run here)
response = client.responses.create(
model="gpt-6-astra",
input="Write a one-sentence bedtime story about a unicorn.",
)
print(response.output_text)This snippet uses OpenAI's Python library, which builds and sends the call for you. Under the hood it is the same kind of POST. The docs' REST examples use the address and header named above. The cap on writing is called max_output_tokens, and the docs say it counts visible output and also reasoning tokens, the hidden thinking some models do.
Google: the Gemini API
Google's text docs now show a call to /v1beta/interactions. The key goes in a header named x-goog-api-key. A second header, Api-Revision, names the revision. The body has a model and an input. Settings live in a nested object called generation_config, where the docs use max_output_tokens.
# From the Gemini API text generation docs, shown without its output (not run here)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-4-hydrogen",
"input": "How does AI work?"
}'Tip
Shapes change. These were checked on 16 November 2026. Before you build, open the vendor's current docs and compare. Older tutorials online may show a different address or different field names.
Where the three differ
The five parts match. The names and the nesting do not. Here is the same list of parts, one line per vendor.
Claude
Key in x-api-key plus a version header. The input is a messages list. The cap is max_tokens and it is required.
OpenAI
Key as a Bearer token. The input is a string or a list of items with content parts. The cap is max_output_tokens.
Gemini
Key in x-goog-api-key plus a revision header. The input is a string in the docs' example. The cap sits inside generation_config.
This is why product teams often write one small function of their own that sends a call and returns one tidy record, so the rest of the app never sees these differences. You will build the reading half of that function below.
What comes back
Every reply holds three things: the text, the usage counts and a stop reason. They sit in different places.
Claude
A content list of blocks. A text block looks like {"type": "text", "text": ...}. The stop_reason says why it stopped: "end_turn" means it reached a natural stopping point, "max_tokens" means it hit the cap. The usage object has input_tokens and output_tokens.
OpenAI
An output list of items. A message item holds content parts of type output_text. A status says completed or incomplete. If it is incomplete, incomplete_details has a reason, such as max_output_tokens. The usage object has input_tokens and output_tokens. The output_text shortcut is only in OpenAI's Python and JavaScript libraries, not in the raw reply.
Gemini
A steps list. A step of type model_output holds content of type text. A status says completed, or incomplete, which the docs explain as finished but with incomplete results, for example hitting max_tokens. The usage object has total_input_tokens and total_output_tokens.
Notice that all three give you counts for what you sent and what you got back. Keep them. They let you see what each feature costs, long before the bill arrives. Costs change often, so we use no prices here.
Notice also that the three vendors say "finished" and "cut short" in different words. If you only read the text, you may show half an answer as if it were whole. Always check the stop reason.
Quick check
A reply comes back with a stop reason of "max_tokens". What happened?
Keep your key out of your code
Your key is a password that spends your money. Anyone who holds it can run calls on your bill. So it never goes in your code, and never goes in a web page.
In an environment variable
The vendors' own docs do this. Claude's docs say its libraries read ANTHROPIC_API_KEY. OpenAI's say each of its libraries reads your key from the system environment, with the example name OPENAI_API_KEY. Google's example uses GEMINI_API_KEY.
Never in the browser
Code in a web page can be read by anyone who opens it. Send the call from your own server, and let your page talk to your server. One vendor's error docs say this plainly for some accounts: send the request from your own back end.
Never in git
Do not commit it, even in a private repository. If a key leaks, make a new one in the vendor's dashboard and delete the old one.
Tip
A good habit: your program should only ever print whether a key is set, never the key itself. The program below does exactly that.
When a call fails
Calls over the internet fail more than local code does. Plan for four cases from day one. Each one needs a different reaction.
Bad key (401)
The key is wrong, revoked or expired. Claude's docs name this authentication_error, and OpenAI's list 401 for an incorrect key. Do not retry. Fix the key.
Rate limit (429)
You sent too much too fast. Claude names it rate_limit_error. OpenAI's docs say to pace your requests and follow the Retry-After header when present. Wait, then retry.
Overloaded (529 or 503)
The vendor is busy. Claude's docs name 529 overloaded_error. OpenAI names 503 server_is_overloaded and says to follow Retry-After, then retry. Wait and try again.
Timeout (504)
The call took too long. Claude's docs name timeout_error and suggest streaming for long requests. The Streaming Responses lesson covers that.
The retry advice has one more detail. Google's troubleshooting guide says to use exponential backoff, which means waiting 1 second, then 2, then 4, and so on. It adds random jitter, a little random extra wait, so many clients do not all retry at once. It says to retry only on 429, 408 or 5xx errors, and to set a maximum number of tries. Client errors such as 400, 402 or 403 point to a bad key or a bad request, so retrying changes nothing.
Quick check
Your call returns a 401 error. What is the best next step?
A real model also differs from the stand-in you are about to use in other ways. It is slower, it costs money for every token, it can give a different answer each run, and it can fail or refuse. Your code must cope with all of that.
Try it: three shapes, one record
Now let's practice. First we build three request bodies for the same question, using the field names exactly as the docs above show them. Nothing is sent anywhere. These are only Python dictionaries (labelled lists of values). The model name is a placeholder, so no real model name is invented.
import json
question = "Why is the sky blue?"
MODEL = "MODEL_NAME_HERE" # a placeholder, not a real model name
claude_body = {
"model": MODEL,
"max_tokens": 200,
"messages": [{"role": "user", "content": question}],
}
openai_body = {
"model": MODEL,
"input": question,
"max_output_tokens": 200,
}
gemini_body = {
"model": MODEL,
"input": question,
"generation_config": {"max_output_tokens": 200},
}
for name, body in [("Claude", claude_body), ("OpenAI", openai_body), ("Gemini", gemini_body)]:
print(name, json.dumps(body))
print("Nothing was sent. These are only dictionaries.")Output
Claude {"model": "MODEL_NAME_HERE", "max_tokens": 200, "messages": [{"role": "user", "content": "Why is the sky blue?"}]}
OpenAI {"model": "MODEL_NAME_HERE", "input": "Why is the sky blue?", "max_output_tokens": 200}
Gemini {"model": "MODEL_NAME_HERE", "input": "Why is the sky blue?", "generation_config": {"max_output_tokens": 200}}
Nothing was sent. These are only dictionaries.Read the output line by line. Same question, same cap of 200, three shapes. Claude's body carries max_tokens at the top and a messages list. OpenAI's carries input and max_output_tokens. Gemini's nests its cap inside generation_config.
Now the reply side. The code below has three stand-in replies, written by hand in the shapes the docs show. They are the stand-in for a model, so the code runs free. A real model is slower, costs money for every token, can give a different answer each run, and can fail or refuse. Each stand-in holds made-up numbers: 12 tokens in, and 8 or 5 out. The OpenAI one pretends it was cut short by the cap.
The three functions from_claude, from_openai and from_gemini each dig into their own shape and turn it into one record with text, input_tokens, output_tokens and stop. The helper plain maps each vendor's "finished" and "cut short" words to "done" and "cut_off". The last lines read each key with os.environ.get and print only whether it is set. We ran it with none set.
import os
# Stand-in replies, shaped like the docs show. Nothing here came from a real model.
claude_reply = {
"type": "message", "role": "assistant",
"content": [{"type": "text", "text": "Air scatters blue light most."}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 12, "output_tokens": 8},
}
openai_reply = {
"object": "response", "status": "incomplete",
"incomplete_details": {"reason": "max_output_tokens"},
"output": [{"type": "message", "role": "assistant",
"content": [{"type": "output_text", "text": "Air scatters blue light"}]}],
"usage": {"input_tokens": 12, "output_tokens": 5},
}
gemini_reply = {
"object": "interaction", "status": "completed",
"steps": [{"type": "model_output",
"content": [{"type": "text", "text": "Air scatters blue light most."}]}],
"usage": {"total_input_tokens": 12, "total_output_tokens": 8},
}
# Each vendor words "finished" and "cut short" differently. We use two words.
DONE = {"end_turn", "completed"}
CUT = {"max_tokens", "max_output_tokens", "incomplete"}
def plain(word):
return "done" if word in DONE else "cut_off" if word in CUT else word
def from_claude(r):
text = "".join(b["text"] for b in r["content"] if b["type"] == "text")
stop = plain(r["stop_reason"])
return {"text": text, "input_tokens": r["usage"]["input_tokens"],
"output_tokens": r["usage"]["output_tokens"], "stop": stop}
def from_openai(r):
parts = [c["text"] for item in r["output"] if item["type"] == "message"
for c in item["content"] if c["type"] == "output_text"]
reason = (r.get("incomplete_details") or {}).get("reason")
stop = plain(reason or r["status"])
return {"text": "".join(parts), "input_tokens": r["usage"]["input_tokens"],
"output_tokens": r["usage"]["output_tokens"], "stop": stop}
def from_gemini(r):
parts = [c["text"] for s in r["steps"] if s["type"] == "model_output"
for c in s["content"] if c["type"] == "text"]
stop = plain(r["status"])
return {"text": "".join(parts), "input_tokens": r["usage"]["total_input_tokens"],
"output_tokens": r["usage"]["total_output_tokens"], "stop": stop}
for name, fn, reply in [("Claude", from_claude, claude_reply),
("OpenAI", from_openai, openai_reply),
("Gemini", from_gemini, gemini_reply)]:
print(name, fn(reply))
for var in ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY"]:
print(var, "is set" if os.environ.get(var) else "is not set")Output
Claude {'text': 'Air scatters blue light most.', 'input_tokens': 12, 'output_tokens': 8, 'stop': 'done'}
OpenAI {'text': 'Air scatters blue light', 'input_tokens': 12, 'output_tokens': 5, 'stop': 'cut_off'}
Gemini {'text': 'Air scatters blue light most.', 'input_tokens': 12, 'output_tokens': 8, 'stop': 'done'}
ANTHROPIC_API_KEY is not set
OPENAI_API_KEY is not set
GEMINI_API_KEY is not setAll three records now look alike. The Claude and Gemini replies both say "done" and have 8 output tokens. The OpenAI reply says "cut_off" and has 5 output tokens, and its text ends early, with no "most". That is the stop reason doing its job. If you had only read the text, you would not know.
If you set a key in your own terminal, the last three lines would say "is set". The program still would not print the key. Nothing in this program was sent over the internet.
Recap
Same five parts
Endpoint, key in a header, model name, input with settings, and a reply with text, usage and a stop reason.
Different names
Messages, input items or a plain input, and nested settings. Always copy from the vendor's current docs.
Safe and ready to fail
Keys in environment variables, calls from your server, and a plan for bad keys, rate limits, overload and timeouts.
Tip
Everything here was checked against each vendor's public docs on 16 November 2026. Fields and model names move, so recheck before you ship.
Next: OpenAI-compatible APIs, one shape many providers copy.
Sources
Last updated on 16 November 2026
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.