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

# Messages.

> The Anthropic Messages dialect on the Layer X1 catalog — the surface Claude Code and the Anthropic SDKs speak. Content blocks, tools, vision, and PDFs, with SSE streaming.

## Endpoint

```http theme={null}
POST /v1/messages
```

Authenticate with `x-api-key: lx1_...` (a bearer token also works). Any model in the
[catalog](/models) is valid in `model`.

## Request parameters

| Parameter        | Type               | Notes                                                                                                                    |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `model`          | string · required  | Any catalog id, e.g. `lx1-sonnet-4.6`.                                                                                   |
| `max_tokens`     | integer · required | Output ceiling. On reasoning models, hidden reasoning counts against it — budget generously.                             |
| `messages`       | array · required   | Alternating turns. Content is a string or an array of blocks: `text`, `image` (base64), `document` (PDF), `tool_result`. |
| `system`         | string \| array    | System prompt.                                                                                                           |
| `tools`          | array              | Tool definitions with JSON-schema input. See [Tool calling](/guides/tool-calling).                                       |
| `tool_choice`    | object             | `{ "type": "auto" \| "any" \| "tool" }`.                                                                                 |
| `temperature`    | number             | Sampling temperature.                                                                                                    |
| `top_p`          | number             | Nucleus sampling.                                                                                                        |
| `stop_sequences` | string\[]          | Custom stop sequences.                                                                                                   |
| `stream`         | boolean            | Anthropic SSE event stream when `true`.                                                                                  |
| `thinking`       | object             | `{ "type": "enabled" }` surfaces the model's reasoning as a `thinking` block. See [Reasoning](/guides/reasoning).        |
| `metadata`       | object             | `metadata.user_id` doubles as a conversation-stable cache-affinity hint. See [Prompt caching](/guides/prompt-caching).   |

<Note>
  Image blocks need a model that declares `capabilities.vision`, and PDF `document` blocks
  a model that declares `capabilities.documents` — both are short lists, so read them off
  [`GET /v1/models`](/api/models-endpoint) rather than guessing. A model that cannot read
  images rejects them with a `400`. See [Vision](/guides/vision).
</Note>

## Example

<CodeGroup>
  ```sh curl theme={null}
  curl https://api.layerx1.com/v1/messages \
    -H "x-api-key: $LAYERX1_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "model": "lx1-sonnet-4.6",
      "max_tokens": 512,
      "system": "You are concise.",
      "messages": [{ "role": "user", "content": "Say hi." }]
    }'
  ```

  ```python Python theme={null}
  import anthropic

  client = anthropic.Anthropic(
      base_url="https://api.layerx1.com",
      api_key="lx1_your_key",
  )

  msg = client.messages.create(
      model="lx1-sonnet-4.6",
      max_tokens=512,
      system="You are concise.",
      messages=[{"role": "user", "content": "Say hi."}],
  )
  print(msg.content[0].text)
  ```

  ```ts TypeScript theme={null}
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic({
    baseURL: "https://api.layerx1.com",
    apiKey: process.env.LAYERX1_API_KEY,
  });

  const msg = await client.messages.create({
    model: "lx1-sonnet-4.6",
    max_tokens: 512,
    system: "You are concise.",
    messages: [{ role: "user", content: "Say hi." }],
  });
  console.log(msg.content[0].type === "text" ? msg.content[0].text : "");
  ```
</CodeGroup>

```json title="Response (shape)" theme={null}
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "lx1-sonnet-4.6",
  "content": [{ "type": "text", "text": "Hi." }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 14, "output_tokens": 3 }
}
```

## Response fields

| Field         | Notes                                                                 |
| ------------- | --------------------------------------------------------------------- |
| `content`     | Array of blocks — `text`, and `tool_use` when the model calls a tool. |
| `stop_reason` | `end_turn`, `max_tokens`, `stop_sequence`, or `tool_use`.             |
| `usage`       | Input and output token counts for the request.                        |

## Streaming

With `stream: true` the response is the Anthropic SSE event sequence —
`message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`,
`message_delta`, `message_stop` — exactly what the Anthropic SDKs expect.

<CodeGroup>
  ```sh curl theme={null}
  curl -N https://api.layerx1.com/v1/messages \
    -H "x-api-key: $LAYERX1_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "model": "lx1-gpt-oss-120b",
      "max_tokens": 256,
      "stream": true,
      "messages": [{ "role": "user", "content": "Count to five." }]
    }'
  ```

  ```python Python theme={null}
  with client.messages.stream(
      model="lx1-gpt-oss-120b",
      max_tokens=256,
      messages=[{"role": "user", "content": "Count to five."}],
  ) as stream:
      for text in stream.text_stream:
          print(text, end="")
  ```

  ```ts TypeScript theme={null}
  const stream = client.messages.stream({
    model: "lx1-gpt-oss-120b",
    max_tokens: 256,
    messages: [{ role: "user", content: "Count to five." }],
  });
  stream.on("text", (t) => process.stdout.write(t));
  await stream.finalMessage();
  ```
</CodeGroup>

## Errors

Failures return standard status codes with Anthropic-shaped bodies
(`{ "type": "error", "error": { ... } }`). Retry on `429`/`5xx` with backoff and honor
`retry-after`. Full reference: [Errors](/errors).