Create chat completion
create_chat_completionSend OpenAI-format chat messages to any supported model to get text, tool calls, or images. Use it when you need one completions endpoint across Anthropic, Gemini, and OpenAI routes.
Instructions
OpenAI-compatible chat completions endpoint, multiplexed across every model Gumloop supports
(Anthropic, OpenAI, Google Gemini, OpenRouter routes). Set stream: true for Server-Sent Events,
or omit it for a unary JSON response. Image-generation models (gpt-image-*, gemini-*-image-preview,
dall-e-*) are dispatched automatically when modalities includes "image" and yield image
attachments on choices[0].message.images.
Streaming host
Chat completions live on the streaming host. Send all requests — unary or streaming — to:
POST https://ws.gumloop.com/api/v1/chat/completionsapi.gumloop.com does not serve this endpoint; the Python SDK routes there automatically.
Tool calls, images, and tool_choice
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 (withtool_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_urlcontent parts alongsidetextparts. The URL can be anhttp(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 whentoolsare sent),"none","required", or{"type": "function", "function": {"name": "..."}}to force one tool.developermessages are treated likesystemmessages.
{
"model": "claude-sonnet-4-5",
"tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}],
"messages": [
{"role": "user", "content": [
{"type": "text", "text": "What's the weather where this photo was taken?"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
]},
{"role": "assistant", "content": null, "tool_calls": [
{"id": "call_1", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Ottawa\"}"}}
]},
{"role": "tool", "tool_call_id": "call_1", "content": "12°C and sunny"}
]
}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:.
Billing
Each completion charges the caller's credit balance based on token usage (with cache-token semantics per provider) plus a flat 30-credit fee for image-gen calls. Users who configure their own provider API key get a 50% discount. Explicit confirmation is required for this exact account operation. Runs can spend credits or trigger downstream actions; never resubmit unknown outcomes automatically.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model slug. Use the `id` from `GET /models` or one of Gumloop's preset routes. | |
| tools | No | OpenAI-shape tool definitions (`{type: "function", function: {name, description, parameters}}`). Pass `tool_choice` to constrain selection. | |
| stream | No | Only non-streaming JSON is supported. Streaming requests are refused before fetch. | |
| account | No | Named private Gumloop account; selects private credentials and user/team identity. | |
| confirm | No | Set true only when the user asked for exactly this action. | |
| payload | No | Complete JSON request body instead of body flags. Preserves current endpoint fields and values. | |
| messages | No | ||
| provider | No | OpenRouter provider routing config. Caller fields like `sort` and `order` are honored; ZDR/data_collection policy is server-enforced. | |
| modalities | No | Output modalities. Include `"image"` to route to an image-generation model. | |
| temperature | No | Sampling temperature. | |
| tool_choice | No | ||
| image_config | No | ||
| payload_file | No | Regular local JSON body file, at most 5 MB. Cannot be mixed with body flags or payload. | |
| response_format | No | ||
| max_completion_tokens | No | Cap on completion tokens. Replaces the deprecated `max_tokens` field. |