Chat Completions

Send a request

Send the whole conversation in messages on every turn: Chat Completions has no continuation, so a follow-up question carries the turns before it.

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.llm.buzz/api/v1",
    api_key=os.environ["LLM_BUZZ_KEY"],
)
reply = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash",
    messages=[
        {"role": "system", "content": "You answer in one short sentence."},
        {"role": "user", "content": "Which port does HTTPS use?"},
        {"role": "assistant", "content": "HTTPS uses port 443."},
        {"role": "user", "content": "And plain HTTP?"},
    ],
)
print(reply.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.llm.buzz/api/v1",
  apiKey: process.env.LLM_BUZZ_KEY,
});
const reply = await client.chat.completions.create({
  model: "deepseek/deepseek-v4.1-flash",
  messages: [
    { role: "system", content: "You answer in one short sentence." },
    { role: "user", content: "Which port does HTTPS use?" },
    { role: "assistant", content: "HTTPS uses port 443." },
    { role: "user", content: "And plain HTTP?" },
  ],
});
console.log(reply.choices[0].message.content);

curl https://api.llm.buzz/api/v1/chat/completions \
  -H "Authorization: Bearer $LLM_BUZZ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "messages": [
      {"role": "system", "content": "You answer in one short sentence."},
      {"role": "user", "content": "Which port does HTTPS use?"},
      {"role": "assistant", "content": "HTTPS uses port 443."},
      {"role": "user", "content": "And plain HTTP?"}
    ]
  }'

The answer is OpenAI's chat completion object with the additions below. The model name, and the models you can call, come from GET https://api.llm.buzz/api/v1/models (Choosing an API).

The messages array

messages is the conversation in order, with the roles system, developer, user, assistant and tool.

• A developer message is accepted for every model. A provider whose API has no developer role receives it as a system message, so the two roles read the same.
• A system or developer message that comes after the conversation has started stays in place when the provider takes one there. Otherwise its text moves into the user turn at the same place, and the body's x-sgr-ignored-parameters names the move, for example messages.system->folded(system_messages_leading_only).
• Message content is a string or a list of parts. The parts are text and image_url; an image needs a model that lists image among its architecture.input_modalities. A tool message may carry image_url parts beside its text. Images in requests has the rules.
• A tool call's id is an opaque string of 1 to 65,536 characters. Send each one back complete, unchanged, as the tool_call_id of its tool message. Tools and structured output covers the loop.

Request fields

A field llm.buzz deliberately refuses is a 400 before any provider is called, and a value that fails validation is a 400 invalid_parameter with metadata.param naming the field. A field llm.buzz drops is named in the body's x-sgr-ignored-parameters.

Headers

You send:

Every served answer carries:

An answer that asks you to wait, a 429 and some 402 and 503 answers, carries Retry-After: wait that many seconds before you retry.

The answer

A non-streamed answer is OpenAI's chat completion object. llm.buzz adds or fixes these parts:

• choices[0].message holds content, and where they apply reasoning (the model's readable reasoning, left out under reasoning.exclude), tool_calls, and images. A model that makes images returns each as a complete base64 image in images[].image_url.url.
• finish_reason is tool_calls when the turn ends with tool calls, length when it hit the output limit, and stop otherwise, a matched stop sequence included. A stream that fails after it opened finishes with error. native_finish_reason sits beside it.
• system_fingerprint is always null.
• provider is the display name of the provider that answered, after any failover; llm.buzz for llm.buzz's own provider.
• usage is described below. It is left out, never null, when the provider reported no counts.
• x-sgr-ignored-parameters is a key in the body, not a header. It lists every field llm.buzz dropped and every value it changed, with the reason where there is one, such as temperature->dropped(unsupported_by_provider); an unknown field is named bare. Check it when a setting seems to have no effect.

Stream

Set stream: true and the answer arrives as server-sent events: data: lines, each one chat.completion.chunk, ending with data: [DONE].

While the model is silent, comment lines beginning with : keep the connection active; clients skip them. Closing a stream sent without an Idempotency-Key stops the request, and the prompt and the output produced up to then are billed. Streaming covers the event shapes of all three text APIs.

Usage and cost

Cache reads and writes are separate parts of prompt_tokens. A cache field appears only when the provider reported it, except that a stream's usage chunk shows cached_tokens: 0 when the count is unknown. cost is a JSON number that includes any billed tool-search rounds, so it can exceed the counts times the listed prices. A failed attempt that another provider replaced adds 0. It is left out when any part of the cost is unknown; a model with no price reports 0. A replay with the same Idempotency-Key returns the original cost. Usage and limits covers the rest, and Prompt caching the cache fields.

Retries

Send an Idempotency-Key header and a retry with the same key and the same body never runs the request twice: it returns the first answer with its original cost, or 409 idempotency_replay_unavailable when that answer is not stored where the retry arrived. That 409 means the first request ran or is still running, so retry with the same key after a short backoff. The exception is a first call that ended in an error answer: its key answers 409 for good, so send a new key. What to send next tells the cases apart.

• The same key with another body is 409 idempotency_conflict. A changed suffix or provider hint counts as another body; a changed stream_options.include_usage does not.
• A retry without the key, or with a new one, runs the request again and bills it again.
• A stream you drop while it carries a key keeps running, and a retry with the key joins it instead of starting a second generation. Without a key, two requests with the same prompt are two requests.
• A provider that fails or times out before output reaches you is replaced by the next one, and the failed attempt costs nothing; a provider's own 400 is not tried on another provider. Once output has reached you, the request stays on the provider that sent it.

Retries and idempotency explains the rest.

Errors

Errors come in OpenRouter's envelope. metadata.gateway_code is the code to branch on, and metadata.param names the field at fault.

{"error": {"code": 400, "message": "...", "metadata": {"error_type": "invalid_request", "gateway_code": "unsupported_parameter", "param": "seed"}}}

A stream that fails after output ends with the error chunk described under Stream. Errors lists every code, including the key, balance, model and provider errors this API shares with the others.

Limits

• One completion per request: n is 1.
• A model's context window is context_length on its entry in GET https://api.llm.buzz/api/v1/models, and top_provider.max_completion_tokens is its output ceiling.
• A request may run for 600 seconds. A stream still generating then ends with a timeout error chunk and data: [DONE], and is billed for the prompt and the output you received. A request that is not streaming answers 504 deadline_exceeded.
• A request body over 64 MiB answers 413 request_too_large.
• A request makes at most 8 provider calls, every fallback included; gateway.retry lowers the ceiling.

Usage and limits collects the limits of every API.

Related

• Tools and structured output, Streaming, Reasoning, Images in requests and Prompt caching cover what the three text APIs share.
• Responses and Messages are the other two text APIs; Choosing an API compares them.
• Coming from OpenRouter lists every difference from OpenRouter in one place.