> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withhopper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat completions

`POST /v1/chat/completions` generates a chat completion. See [Models](/models) for model IDs and pricing. This page documents the fields Hopper defines or constrains.

## Request

* `model` (string, required) — `gemma-4-31b`.
* `messages` (array, required) — Prompt and history. The context limit, including input and output, is 262,144 tokens for Gemma 4 31B.
* `stream` (boolean, optional, default `false`) — Returns a Server-Sent Events stream of `chat.completion.chunk` objects.
* `tools` (array, optional) — Function definitions the model may call.

The request body is limited to 10 MB; a larger body returns 413.

## Streaming

On `stream: true`, Hopper sets `stream_options.include_usage` on the upstream request and removes the resulting usage chunk unless you sent that option yourself.

<CodeGroup>
  ```python Python theme={null}
  import os

  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.withhopper.com/v1",
      api_key=os.environ["HOPPER_API_KEY"],
  )

  stream = client.chat.completions.create(
      model="gemma-4-31b",
      messages=[{"role": "user", "content": "Count to five."}],
      stream=True,
  )
  for chunk in stream:
      print(chunk.choices[0].delta.content or "", end="", flush=True)
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.withhopper.com/v1",
    apiKey: process.env.HOPPER_API_KEY,
  });

  const stream = await client.chat.completions.create({
    model: "gemma-4-31b",
    messages: [{ role: "user", content: "Count to five." }],
    stream: true,
  });
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  }
  ```

  ```bash cURL theme={null}
  curl -N https://api.withhopper.com/v1/chat/completions \
    -H "Authorization: Bearer $HOPPER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemma-4-31b",
      "messages": [{"role": "user", "content": "Count to five."}],
      "stream": true
    }'
  ```
</CodeGroup>

## Tool calling

Pass `tools`; when the model calls one, the response message carries `tool_calls` instead of content.

<CodeGroup>
  ```python Python theme={null}
  import os

  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.withhopper.com/v1",
      api_key=os.environ["HOPPER_API_KEY"],
  )

  tools = [
      {
          "type": "function",
          "function": {
              "name": "get_balance",
              "description": "Return the account balance in dollars.",
              "parameters": {
                  "type": "object",
                  "properties": {"account_id": {"type": "string"}},
                  "required": ["account_id"],
              },
          },
      }
  ]

  response = client.chat.completions.create(
      model="gemma-4-31b",
      messages=[{"role": "user", "content": "What is the balance on account a-17?"}],
      tools=tools,
  )
  print(response.choices[0].message.tool_calls)
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.withhopper.com/v1",
    apiKey: process.env.HOPPER_API_KEY,
  });

  const tools = [
    {
      type: "function" as const,
      function: {
        name: "get_balance",
        description: "Return the account balance in dollars.",
        parameters: {
          type: "object",
          properties: { account_id: { type: "string" } },
          required: ["account_id"],
        },
      },
    },
  ];

  const response = await client.chat.completions.create({
    model: "gemma-4-31b",
    messages: [{ role: "user", content: "What is the balance on account a-17?" }],
    tools,
  });
  console.log(response.choices[0].message.tool_calls);
  ```

  ```bash cURL theme={null}
  curl https://api.withhopper.com/v1/chat/completions \
    -H "Authorization: Bearer $HOPPER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemma-4-31b",
      "messages": [{"role": "user", "content": "What is the balance on account a-17?"}],
      "tools": [{
        "type": "function",
        "function": {
          "name": "get_balance",
          "description": "Return the account balance in dollars.",
          "parameters": {
            "type": "object",
            "properties": {"account_id": {"type": "string"}},
            "required": ["account_id"]
          }
        }
      }]
    }'
  ```
</CodeGroup>

Send the tool result back as a `tool` message with the matching `tool_call_id` to continue the conversation.

Error codes are listed in [Errors](/errors).