Parameters

The identifier from the catalogue, in the form vendor/model. It decides both what answers and at what rate, and it is never quietly swapped for something close: an identifier that is not in the catalogue — a missing or empty model included — comes back 404, and one that is listed but not served yet comes back 400 saying so.

It also decides which reply you get on chat/completions: a text model answers with text, an image model with a frame, and the catalogue says which is which in architecture.output_modalities. The other two routes are not interchangeable: a text model named on /api/v1/images, or an image model named on the Messages route, is refused with 400 rather than answered from the wrong place, because a request that quietly lands on the wrong executor surfaces later as a strange reply and gets debugged in the prompt.

The conversation, in the shape the OpenAI libraries send. On a text model every turn travels as itself: system and developer become the standing instruction wherever they stand in the array, user carries text and image_url parts, assistant carries earlier answers and their tool_calls, and tool carries a result under its tool_call_id. On an image model the text of all messages is joined into one instruction with the framing parts placed first, and images attached in any image_url part are collected from the whole array as references. On the Messages route the array is the model's own and travels untouched.

Structure that cannot be read is 400 naming the position: a message that is not an object, a content that is neither string nor array, an image_url without a url string, a tool call without an id or a name. A content part of a kind we cannot use — audio, a file — is a 400 on a text model, because dropping it would change the question; on an image model it is skipped instead.

The instruction for the images route, which takes a single string instead of an array. It is checked before anything is reserved or spent, so a body without it — or with null, an empty string, or a value that is not a string at all — costs nothing and comes back 400. On chat/completions the instruction comes from messages and this field is not read.

The frames to work from on the images route. An item is either a data URL or an http(s) URL, written as a bare string or as an object with image_url. Links are fetched before the balance is touched, so one that does not open is a 400 naming which reference failed, and nothing is charged for it.

On chat/completions the same job belongs to image_url parts inside messages; the limit of sixteen attachments is shared by both. Attachments to an image model are billed as input at the model's input rate, at a fixed count of about 2,900 tokens each; the catalogue's pricing.image is that count at the input rate. An image sent to a text model is not fetched by us at all: a data URL travels as bytes, and a link is opened by the model provider.

On an image model, how many frames come back from one request; each of them is charged. A number above the ceiling is brought down to it rather than refused, so asking for fifty returns ten. On a text model the only accepted value is 1: n: 2 is 400, because two answers would be two requests and two charges under one identifier. A value that is not a number is 400 everywhere.

This one is read at the top level only. Inside image_config it has no effect, unlike the geometry fields below.

Turns the reply into server-sent events on all three routes. On the two OpenAI-shaped routes the value has to be a real boolean — the string "true" is 400, because a stream and a single JSON document are two different replies and guessing wrong breaks the parsing either way.

A text model streams as it writes, on either text route. A streamed frame is still a finished frame: the events carry the whole image when it is ready, not a picture that fills in. stream_options is accepted next to it and changes nothing — the last chunk of a text stream carries usage whether or not include_usage asked for it. Event shapes and how a stream ends→

Both are accepted on the OpenAI-shaped routes and neither is executed. They are taken rather than refused because a client that sends them on every call is not doing anything wrong, and they are named here rather than passed over in silence because seed promises repeatability: two identical requests with the same seed will still differ, and someone comparing them would go looking for the reason in the prompt.

On a text model the same treatment — accepted, dropped before the request goes upstream, a line in our log — applies to response_format, logit_bias, logprobs, presence_penalty and frequency_penalty: the executor has no equivalent, and there is no JSON mode on this gateway.

Each entry is {type: "function", function: {…}} with a name, an optional description and a JSON-schema parameters object; a tool declared without a schema gets an empty object schema. The model answers with tool_calls and finish_reason: "tool_calls" when it wants one run; you run it and post the result back as a message with role: tool. An entry that is not a function, or a function without a name, is 400 naming its position.

auto lets the model decide, none forbids tool use for this turn, required demands one, and {type: "function", function: {name}} names the one to call. Any other value is 400. Sent without tools it is dropped rather than refused: many clients send tool_choice: "auto" by default, and refusing on it would close the door to those that asked for no tools at all.

false makes the model call at most one tool per turn. It is read together with tool_choice and has no meaning without tools.

Prompt caching, in both forms the OpenAI shape allows. On a text or image_url part it is an explicit cache point: everything up to that part is written to the cache on the first call and read from it on the next. At the top level of the body it is the automatic form: the point is placed on the last block of the conversation and moves forward as the conversation grows. Cache writes and reads are billed at their own rates, published per model in the catalogue, and what was read is reported in usage.prompt_tokens_details.cached_tokens. On the Messages route the same marks travel on content blocks in the native shape.

The upper limit on what the model may generate in reply. It also decides how much of your balance is held while the request runs: the reserve is taken against this ceiling and settled against the tokens actually used, so an inflated max_tokens can make a request fail on balance that would otherwise have fit. How the reserve works→

The executor requires a ceiling, and the OpenAI shape does not: on chat/completions a body without one gets 4096 filled in, and the field is also read under its newer name max_completion_tokens. On the Messages route nothing is filled in, and a body without it is refused by the model with its own 400.

The ceiling of the model itself is lower than any number you can write, and asking for more than it allows is refused with its own message — max_tokens: 100000 > 64000 and the like — relayed as 400.

This setting influences the variety in the model's responses. Lower values lead to more predictable and typical answers, higher ones to more diverse and less common ones. At 0 the same input gives you very nearly the same output every time.

Some models refuse this field outright. For those it is removed before the body goes upstream, on either text route, rather than answered with a 400 — and the catalogue leaves it out of that model's supported_parameters, which is where to confirm what the model you are calling accepts.

This limits the choice to the most likely tokens whose probabilities add up to P. A lower value makes the answer more predictable; the usual setting leaves the full range of choices open.

It and temperature narrow the same choice from different ends, and turning both at once makes the result hard to reason about — pick one. The models that refuse temperature refuse this one too, and it is removed for them the same way.

This limits the model's choice of tokens at each step to a smaller set. A value of 1 means it always takes the single most likely next token, which is as predictable as the model gets. Left unset, all the candidates stay in play. Confirm what the model you are calling accepts.

Generation stops as soon as one of these strings appears, and the string itself is not part of the reply. Useful when you are parsing the output and a delimiter is the honest end of it.

On chat/completions the field is stop and takes a single string or an array, as in the OpenAI shape; on the Messages route it is stop_sequences, always an array. The catalogue lists it under the normalised name stop. Confirm what the model you are calling accepts.

The standing instruction for the whole exchange. On the Messages route it is a field of its own, not the first element of messages, and a system message pushed into the array instead is not the same thing.

On chat/completions the equivalent is a message with role: system or role: developer. A text model receives it as its standing instruction, wherever it stands in the array; an image model reads it first and puts it at the front of the prompt — framing goes ahead of what it frames. An image inside a system message is a 400 on a text model.