How chat completions and the Messages API differ

The book’s agent talks to models through one interface, Model, with one method. Behind it sit two clients: one for the chat completions format, which OpenRouter, OpenAI, and many local servers accept, and one for Anthropic’s Messages API. Chapter 11 writes the second as an adapter and lists what an adapter for any API has to decide. This page collects the answers for the two APIs the book covers into one table, so you can see the size of the job before you start a third.

Facts below are from chapters 2, 4, 6, 8, and 11, checked against the companion code, as of October 2026. Provider APIs change; each row names the place in the code to check when one does.

The table

A few rows need more than a cell.

Refusals. A Claude model that declines a request stops with refusal, in a normal reply that can hold some text. The conversation can’t usefully continue from there, so the book’s loop counts it among the replies it can’t continue from and stops with ErrRefused, a new member of the bad-reply family in chapter 11. Here is the whole mapping, from the companion code:

// finishReason maps a stop reason onto the finish reasons the loop
// checks (chapter 5). A refusal is its own reason, which the loop turns
// into ErrRefused. pause_turn comes only from server-side tools, which
// this agent doesn't use, so it can't be continued here.
func finishReason(stop string) string {
	switch stop {
	case "end_turn", "stop_sequence":
		return "stop"
	case "tool_use":
		return "tool_calls"
	case "max_tokens", "model_context_window_exceeded":
		return "length"
	case "refusal":
		return "refusal"
	}
	return "error" // pause_turn, or a reason this client doesn't know
}

Reasoning and hosts. OpenRouter routes one Claude model to several hosts, each under its own account. In chapter 11’s experiment, a thinking block sent back to the host that wrote it was accepted in both runs, and sent to any of three other hosts it was refused with a 400. That is why the adapter records where reasoning came from, and why chapter 13 later pins one host.

Stream size. Over the 13 replies of each recorded run of the same task, the Messages API’s stream had a median of 64 events per reply, and chat completions’ 31; per output token, about 1.2 times as many. The adapter turns each event into at most one of the loop’s Delta values, so the loop never learns which format it is reading.

Bytes on the wire

Each format writes the same conversation its own way, and the sizes come out close. Chapter 11 encoded one request, the last of a recorded run, with each client:

Without its reasoning, the chat completions conversation was within about 1 percent of the Messages API’s. The Messages API request carried no reasoning because that reasoning came from another client, and sending it would break the rule in the reasoning row above.

Other servers that speak chat completions

The chat completions format is the one many servers accept, and the book’s client reads its address from OPENROUTER_BASE_URL. Chapter 2 points it at a local Ollama server, http://localhost:11434/v1, with no other change. Two things differ there: the program needs any non-empty key to stop replaying, and fields only OpenRouter sends, such as each call’s cost, read as zero, so a dollar budget does nothing. More providers lists the native APIs of Gemini, Ollama, Bedrock, and Cohere, with their official documentation.

Writing a third adapter

For any new API, the rows of the table are the questions. Answer each one in code, keep the API’s format inside its adapter, and test it two ways: httptest replies for each error and edge case, and a recorded run replayed through the client. For scale, chapter 11’s Messages API client, ch11/anthropic, is 1,559 lines of Go in 6 files, its tests included.