---
title: "Chat completions API (OpenAI-compatible)"
description: "OpenAI-compatible /v1/chat/completions with inline parameters, examples, streaming, tools and cache usage notes."
source: https://lazu.ai/docs/endpoints/chat
updated: 2026-10-02
---

# Chat completions

**POST** `/v1/chat/completions`

Send OpenAI-compatible chat requests through Lazu. Use this page as the working reference: base URL, auth, required body fields, examples, response usage, streaming and tool calling all live here.

## Example request

```bash
curl https://api.lazu.ai/v1/chat/completions \
  -H "Authorization: Bearer $LAZU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [
      {"role": "user", "content": "Say hello from Lazu"}
    ]
  }'
```

## Example response

```json
{
  "id": "chatcmpl-9aZx",
  "model": "gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 11, "completion_tokens": 3 }
}
```

## Basic configuration

- **Base URL** — Use `https://api.lazu.ai/v1` with OpenAI SDKs, or call the full
  path `https://api.lazu.ai/v1/chat/completions` directly.
- **Model discovery** — Read `GET /api/models/catalog` at runtime. Filter entries where
  `supported_endpoint_types` contains `chat`.

## Request body

- `model` `string` (required) — Model ID, route alias or future route policy name. For explicit models, pass
  IDs from `GET /api/models/catalog`. For SDK compatibility,
  `/v1/models` remains available as a flat list.
- `messages` `object[]` (required) — Ordered conversation messages. Roles follow the OpenAI shape:
  `system`, `user`, `assistant`, and
  `tool`.

  - `role` `string` — One of system, user, assistant or tool.
  - `content` `string | content_part[]` — Plain text, or an array of content parts for multimodal requests.
  - `tool_call_id` `string` — Required on tool messages so the model can associate the result with the earlier call.
- `stream` `boolean` (optional) — When `true`, Lazu forwards a Server-Sent Events stream and ends
  with `data: [DONE]`.
- `tools` `object[]` (optional) — Function/tool definitions. Check `parameters.tools` in the model
  catalog before sending tools to a model.

  - `type` `"function"` — Only function tools are supported today.
  - `function.name` `string` — Tool name the model will call.
  - `function.parameters` `object` — JSON Schema describing the tool arguments.
- `tool_choice` `string | object` (optional) — OpenAI-compatible tool choice control. Use `auto`,
  `none`, `required`, or a named tool object when the
  selected model supports it.
- `response_format` `object` (optional) — Structured output control. Use `{"type":"json_object"}`
  or a JSON schema object when the model supports strict structured output.
- `temperature` `number` (optional) — Sampling temperature. Most models accept `0` to `2`,
  but provider-specific limits can differ.
- `max_tokens` `integer` (optional) — Maximum generated tokens. The final cap is still bounded by the selected
  model's context and output limits.
- `stream_options` `object` (optional) — Use `{"include_usage":true}` when the upstream supports
  streaming usage trailers.

## Message content

- `role` `string` (required) — Message role. One of: `system`, `user`, `assistant`, `tool`
- `content` `string | content_part[]` (required) — Plain text for text-only turns, or an array of content parts for multimodal
  requests.
- `tool_calls` `object[]` (optional) — Assistant tool calls returned by the model.
- `tool_call_id` `string` (optional) — Required on `tool` messages so the model can associate a tool
  result with the earlier tool call.

## Vision input

For image input, send OpenAI-compatible content parts. Use either HTTPS image
URLs or data URLs:

**Image input**

```json
{
"model": "gpt-6-luna",
"messages": [
  {
    "role": "user",
    "content": [
      {"type": "text", "text": "What's in this image?"},
      {
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,..."}
      }
    ]
  }
]
}
```

For PDFs and large documents, upload through [Files](https://lazu.ai/docs/endpoints/files) and use
[Responses](https://lazu.ai/docs/endpoints/responses). Chat completions does not automatically
dereference `file_id`.

## Tools

**Tool definition**

```json
{
"model": "gpt-6-luna",
"messages": [{"role": "user", "content": "Weather in Tokyo?"}],
"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  }
]
}
```

Tool support is not universal. Prefer `/api/models/catalog` and look
at `parameters.tools` before routing agent traffic.

## Response

- `id` `string` — Lazu or provider response ID. Use the response header
  `X-Lazu-Request-Id` for request-level reconciliation.
- `choices` `object[]` — Assistant output choices. Streaming responses send incremental
  `delta` objects.
- `usage.prompt_tokens` `integer` — Prompt input tokens.
- `usage.completion_tokens` `integer` — Generated output tokens.
- `usage.prompt_tokens_details.cached_tokens` `integer` (optional) — Cache read tokens when the upstream reports them.
- `usage.prompt_tokens_details.cache_write_tokens` `integer` (optional) — Cache creation/write tokens when the upstream reports them.
- `usage.prompt_tokens_details.cache_miss_tokens` `integer` (optional) — Cache misses when the provider reports them separately, for example
  DeepSeek-compatible usage.

For complete usage, billing line items, provider raw usage fields and routing
metadata, call:

**Request detail**

```bash
curl https://api.lazu.ai/api/usage/requests/req_lazu_01ABCDEF \
-H "Authorization: Bearer $LAZU_API_KEY"
```

## Errors

Relay errors use OpenAI-compatible error envelopes where possible and include a
request ID. See [Errors](https://lazu.ai/docs/errors) for code meanings and retry behavior.

## See also

- [Model catalog](https://lazu.ai/docs/models/catalog)
- [Responses API](https://lazu.ai/docs/endpoints/responses)
- [Billing and cache fields](https://lazu.ai/docs/billing)
- [Request details](https://lazu.ai/docs/endpoints/usage-requests)