OpenAI & Claude APIs

This is the framing post for the whole day, so it deliberately stays at the level of nouns and mental models before any code. The single most useful idea to internalize is that 'OpenAI' and 'Claude' are not interchangeable endpoints behind one standard — they are two separate commercial APIs from two companies (OpenAI and Anthropic), each with its own request shape, response shape, and defaults.

Getting this clear early prevents the most common beginner confusion, where someone copies an OpenAI tutorial, swaps the model name to a Claude one, and is surprised it 400s. Same problem, two dialects.

Both APIs are ordinary HTTPS REST services. There is no special protocol and no local runtime — your code makes a POST request with a JSON body and an authentication header, and a JSON response comes back. OpenAI authenticates with an Authorization: Bearer header; Anthropic uses an x-api-key header plus an anthropic-version header. The official SDKs hide these details, but it helps to know that underneath it is just HTTP.

Because inference runs on the provider's GPUs, you are billed per token of usage rather than per install or per seat. That single fact drives almost every design decision later in the day: cost, latency, and capability all flow from the fact that you are renting metered inference.

A completion is the atomic operation of both APIs: you supply a list of messages and the model produces the next message continuing the conversation. Chat, agents, RAG, tool use, and vision are all elaborations on this one primitive. If you can build and read a single message-in / message-out call, the rest is configuration.

The mental model worth carrying forward is 'stateless function call'. The API does not remember your previous turns; you resend the whole conversation each time. That is why context windows and token counts matter so much — the entire history rides along in every request.

Tokens are the currency of these APIs, and they are neither characters nor words. A tokenizer breaks text into sub-word units of roughly four characters on average in English, though code, punctuation, and non-English text tokenize less efficiently. You are billed separately for input tokens (everything you send, including system instructions and prior turns) and output tokens (what the model generates).

The context window is the hard ceiling on input plus output for a single request. Exceed it and the call fails or silently truncates depending on the API. Estimating cost and staying inside the window both require counting tokens, not eyeballing word count — a habit that pays off the moment you handle real documents.

This slide names the concrete differences that trip people up. OpenAI's chat endpoint is /v1/chat/completions and returns a choices array, where choices[0].message.content holds the text. Anthropic's endpoint is /v1/messages and returns a content array of typed blocks, where content[0].text holds the text for a normal reply.

The most frequently missed difference is the system prompt: OpenAI takes it as a message with role 'system' inside the messages array, while Claude takes it as a separate top-level 'system' field and additionally requires you to set max_tokens on every request. These are small differences, but they are exactly the ones that cause confusing errors when you assume the two APIs are identical.

The diagram shows the universal request loop both APIs share. Your application builds a JSON payload, sends it over HTTPS with an authentication header (Bearer for OpenAI, x-api-key for Anthropic), the provider runs the model on its hardware, and a response containing the generated text plus a usage object comes back.

Keeping this loop in mind makes debugging tractable. Almost every problem you will hit lives at one identifiable point: malformed JSON or wrong auth (request side), a model or parameter issue (inference side), or a parsing mistake (response side). Knowing which third of the loop failed cuts your debugging time dramatically.

This addresses the natural question: why not just download the model? Frontier models are hundreds of gigabytes and require clusters of high-end GPUs to serve at usable speed. Hosting one yourself means buying or renting that hardware, managing it, and updating weights — an entire infrastructure discipline.

The API model trades control and data locality for zero operational burden and immediate access to the latest version. For most teams that is the right trade, but it is a trade: your prompts leave your network, and you depend on the provider's uptime and pricing. Naming the trade explicitly helps you decide when a self-hosted open model might actually be the better call.

Model identifiers are versioned snapshots, not generic brands. You call gpt-4o or claude-sonnet-4-20250514, each with its own price, speed, context size, and quirks. Providers periodically retire old snapshots and release new ones, sometimes with subtly different behavior.

The practical advice is to pin an exact model string in code or config and treat changing it as a deliberate, tested change. If you let a default float, a provider-side update can shift your outputs overnight, and you will spend a frustrating afternoon chasing a 'bug' that is really just a new model version.

This is the smallest meaningful OpenAI call, and it is worth reading line by line. Constructing OpenAI() with no arguments makes the SDK read the OPENAI_API_KEY environment variable, which is the correct place for the secret. The create call names a model and passes a single user message. The reply text lives at choices[0].message.content.

Notice what is absent: no max_tokens (OpenAI defaults it), no system message, no streaming. That minimalism is intentional — it isolates the irreducible core of an OpenAI request so the additions in later posts are clearly additions, not mysteries.

The Claude equivalent looks similar but exposes the key differences from the previous slide. Anthropic() reads ANTHROPIC_API_KEY. The messages.create call requires max_tokens — leave it out and the request fails — and the reply text lives at content[0].text rather than inside a choices array.

Putting the two minimal calls side by side is the fastest way to build an accurate mental model of the dialects. They are clearly cousins, but the system handling, the required max_tokens, and the response shape are exactly the three places your code must branch when you support both.

This stack diagram places the API in the context of a real product. At the top is your user interface; below it your backend, which owns prompts, keys, retries, and business logic; below that the provider SDK; then the provider's API; and at the bottom the model running on GPUs you never see.

The load-bearing lesson is the boundary between 'your backend' and 'SDK': that is where the API key must live and where the provider-specific code should be isolated. Keep that layer thin and well-defined and you can change models, add retries, or even swap providers without touching the UI above it.

This wraps the conceptual groundwork. You now have the vocabulary — completion, token, context window, model snapshot — and the two minimal calls to anchor it. That foundation is what makes the next four posts legible rather than a blur of parameters.

Day 93 builds directly on this by examining why the choice between these APIs is an architecture decision with long-lived consequences, not a casual setting you can flip later.