---
title: "Use tools, structured output, and streaming"
description: "Test XiuRouter tool calls, JSON Schema output, and Chat Completions streaming separately with your target model."
image: "https://docs.xiu.ai/og.png"
---

> XiuAI documentation index
> Full documentation index: https://docs.xiu.ai/en/llms.txt
> Check the index for current pages before reading.

# Use tools, structured output, and streaming

Tool calling, structured output, and streaming are separate capabilities. First test ordinary text with the same model, then verify each capability you need.

## Tool calling

This request lets the model select a tool; it does not execute the function:

```bash
curl https://router-api.xiu.ai/v1/chat/completions \
  -H "Authorization: Bearer $XIUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"model": "YOUR_MODEL_ID",
"messages": [
  {
    "role": "user",
    "content": "What time is it in Taipei? Use the tool."
  }
],
"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_time",
      "description": "Read the current time in the specified timezone",
      "parameters": {
        "type": "object",
        "properties": {
          "utc_offset": {
            "type": "string"
          }
        },
        "required": ["utc_offset"],
        "additionalProperties": false
      }
    }
  }
],
"tool_choice": "auto"
  }'
```

A successful response includes the tool name and arguments in `choices[0].message.tool_calls`. Your application must then:

1. Validate the tool name and arguments.
2. Execute the tool in a controlled environment.
3. Return the result as a `role: "tool"` message.
4. Read the model's final answer.

If text works but no `tool_calls` appear, check the selected model and service group's tool support. Do not fabricate a tool result in the client.

## Structured output

Chat Completions accepts `response_format`. This example requests a fixed JSON structure:

```bash
curl https://router-api.xiu.ai/v1/chat/completions \
  -H "Authorization: Bearer $XIUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"model": "YOUR_MODEL_ID",
"messages": [
  {
    "role": "user",
    "content": "Classify Beijing as a city."
  }
],
"response_format": {
  "type": "json_schema",
  "json_schema": {
    "name": "city",
    "strict": true,
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "country": {"type": "string"}
      },
      "required": ["name", "country"],
      "additionalProperties": false
    }
  }
}
  }'
```

The gateway parses `response_format`, but the target model may support only `json_object`, reject strict schemas, or lack structured output entirely. Production code must still parse and validate the returned value.

## Streaming

Use `curl -N` to avoid local buffering:

```bash
curl -N https://router-api.xiu.ai/v1/chat/completions \
  -H "Authorization: Bearer $XIUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"model": "YOUR_MODEL_ID",
"messages": [
  {
    "role": "user",
    "content": "Explain an API gateway in three sentences."
  }
],
"stream": true,
"stream_options": {
  "include_usage": true
}
  }'
```

Chat Completions streams normally contain SSE `data:` events and a completion event. Responses uses different event types. Parse the actual protocol rather than mixing the two stream formats.

## Verify the result

- Tools: receive correctly structured `tool_calls` and complete a read-only tool round trip.
- Structured output: validate the response against your JSON Schema.
- Streaming: receive multiple events and a complete termination signal, then confirm the streaming flag and final cost in usage logs.

## Troubleshoot

| Symptom | Next step |
| --- | --- |
| Plain text instead of a tool call | Try a model with verified tool support, or explicitly select a tool through `tool_choice` |
| `response_format` rejected | Use `json_object` or plain text and validate it yourself |
| Stream stops early | Confirm the direct `router-api.xiu.ai` endpoint; keep the request ID and check usage logs first |
| No usage event at the end | The upstream may not support `include_usage`; reconcile with usage logs |
| Tool arguments are not valid JSON | Reject execution, keep the original arguments, and ask the model to generate them again |

## Sources and review date

Reviewed on 2026-08-31. This translation preserves that date. Tool calls, structured output, and stream events vary by model and service tier. Verify each with the actual target model and reconcile the corresponding usage log before production use.

Source: https://docs.xiu.ai/en/router/tools-streaming/index.mdx