Create chat completion

Run one chat completion on any model Gumloop supports (Anthropic, OpenAI, Google Gemini, OpenRouter routes). The request and response use the OpenRouter chat completions schema, which extends OpenAI’s. An OpenAI-style client works unchanged. 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.

Host

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.

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 (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.

{
  "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.