Skip to main content
POST
OpenRouter’s reasoning, plugins, provider, modalities and image_config fields are accepted too.Image-generation models (gpt-image-*, gemini-*-image-preview) run when modalities includes "image" and return image attachments on choices[0].message.images. Decision models (typesafe/jev-*) are not chat models. Send those to POST /decisions.
Chat completions are served from the streaming host, POST https://ws.gumloop.com/api/v1/chat/completions, for both stream: true and stream: false. api.gumloop.com does not serve this endpoint. The Python SDK routes there automatically.With stream: true the response is text/event-stream (Server-Sent Events). Each event carries one chat.completion.chunk and the stream ends with data: [DONE]. client.chat.completions.create(..., stream=True) yields parsed ChatStreamChunk objects.
Send messages in the OpenAI shape and Gumloop translates them for the model’s provider (Anthropic, OpenAI, and Google Gemini). Models served through OpenRouter and other OpenAI-compatible providers receive the messages as sent.
  • Tool-result turns: after the model replies with finish_reason: "tool_calls", append its assistant message (with tool_calls) and one {"role": "tool", "tool_call_id": ..., "content": ...} message per call, then send the conversation again. Every tool call needs a matching tool message, and every tool message must match a tool call in an earlier assistant message.
  • Images: user messages accept image_url content parts alongside text parts. The URL can be an http(s) URL or a base64 data URL (data:image/png;base64,...). Images must be JPEG, PNG, GIF, or WebP and at most 20 MB. Redirects are not followed when downloading an image.
  • tool_choice: "auto" (the default when tools are sent), "none", "required", or {"type": "function", "function": {"name": "..."}} to force one tool.
  • developer messages are treated like system messages.
A request that can’t be translated returns 400 invalid_request with param set to the field at fault (for example messages[3].tool_call_id). When the provider itself rejects the request (HTTP 400, 404, 413, or 422), the error message relays the provider’s reason, prefixed with The provider rejected the request:.
Each completion charges the caller’s credit balance based on the model’s token usage (with cache-token semantics per provider). Image-generation calls are priced the same way, from the usage the image model reports. On usage-based pricing, a call that runs on your own provider API key (BYOK) uses 0 model credits. Organizations still on legacy pricing get a partial BYOK discount instead. See Credits.Gumloop checks credits before sending the request to a provider. Insufficient credits return HTTP 402 credit_limit_exceeded. A provider call whose cost is fully waived because you use your own API key is exempt from this preflight.

Authorizations

Authorization
string
header
required

A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.

Body

application/json
model
string
required

Model slug. Use the id from GET /models or one of Gumloop's preset routes.

Example:

"claude-sonnet-4-5"

messages
object[]
required

Conversation history. Roles system, developer, user, assistant, and tool. User messages accept multipart content with text and image_url parts. Assistant messages can carry tool_calls; answer each one with a tool message whose tool_call_id matches the call's id.

Example:
stream
boolean
default:false

When true, the response is text/event-stream carrying one chat.completion.chunk per delta and terminating with data: [DONE]. Otherwise a unary JSON chat.completion is returned.

temperature
number

Sampling temperature.

max_completion_tokens
integer

Cap on completion tokens. Replaces the deprecated max_tokens field.

modalities
enum<string>[]

Output modalities. Include "image" to route to an image-generation model.

Available options:
text,
image
image_config
object

Image-generation parameters (size, quality, aspect_ratio, background, output_format, partial_images). Optional. Image-generation models accept either modalities: ["image"] or image_config (or both); chat models ignore this field.

response_format
object

Constrain the response. {type: "json_object"} returns a JSON object; {type: "json_schema", json_schema: {name, strict, schema}} returns JSON matching the supplied schema.

tools
array

OpenAI-shape tool definitions ({type: "function", function: {name, description, parameters}}). Pass tool_choice to constrain selection.

tool_choice

"auto" lets the model choose and is the default when tools are sent. "none" disables tool calls, "required" forces a tool call, and {"type": "function", "function": {"name": "..."}} forces a specific tool.

Example:

"auto"

provider
object

OpenRouter provider routing config. Caller fields like sort and order are honored; ZDR/data_collection policy is server-enforced.

reasoning
object

Reasoning settings. effort accepts minimal, low, medium, high, xhigh, max, or none. On Claude models, an unknown effort returns HTTP 400 with param set to reasoning.effort. Claude models return their thinking summary in the response's reasoning; none turns thinking off on Claude models that support disabling it. Only effort and summary are read from this object; other fields are ignored.

Response

Chat completion. When stream is false (or omitted), the response is the chat.completion envelope below. When stream: true, the response is text/event-stream; each event carries one chat.completion.chunk and the terminator is data: [DONE].

id
string
Example:

"chatcmpl-9a3f8c2b14d6e7"

object
string
Example:

"chat.completion"

created
integer
Example:

1747315920

model
string
Example:

"claude-sonnet-4-5"

choices
object[]
usage
object