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

# Messages API — POST /v1/messages | Anthropic Format

> Anthropic-compatible endpoint. Accepts x-api-key or Bearer auth, top-level system field, returns Anthropic-shaped responses. Drop-in for the Anthropic SDK.

The Messages endpoint lets you point codebases that use the Anthropic SDK directly at Piramyd without changing your message structure. It accepts the Anthropic request format — including the top-level `system` field and Anthropic-style message objects — and returns a response shaped to the Anthropic specification. This means you can run Claude models (and any other Piramyd-hosted model) through your existing Anthropic SDK integration by changing only the `base_url`.

<Tip>
  Use the official Anthropic Python or JavaScript SDK and set its `base_url` to `https://api.piramyd.cloud/v1`. Your API key, message format, and response parsing code remain unchanged.
</Tip>

## Endpoint

```
POST https://api.piramyd.cloud/v1/messages
```

***

## Authentication

The Messages endpoint accepts **both** standard Piramyd bearer tokens and the `x-api-key` header used by the Anthropic SDK. Use whichever form your integration already expects.

<CodeGroup>
  ```http Bearer token (standard) theme={null}
  POST /v1/messages HTTP/1.1
  Host: api.piramyd.cloud
  Authorization: Bearer sk-YOUR_KEY
  Content-Type: application/json
  ```

  ```http x-api-key (Anthropic SDK style) theme={null}
  POST /v1/messages HTTP/1.1
  Host: api.piramyd.cloud
  x-api-key: sk-YOUR_KEY
  Content-Type: application/json
  ```
</CodeGroup>

***

## Request Parameters

<ParamField body="model" type="string" required>
  The model ID to use. Retrieve valid IDs from `GET /v1/models`. Example: `claude-opus-4.8`.
</ParamField>

<ParamField body="messages" type="array" required>
  The conversation history as an array of message objects. Each object contains:

  * `role` — `"user"` or `"assistant"`
  * `content` — a string, or an array of typed content blocks (e.g. text, image) for multimodal messages

  Do **not** include system messages here; use the top-level `system` field instead.
</ParamField>

<ParamField body="system" type="string">
  The system prompt. This is a top-level field in Anthropic format — not a message inside the `messages` array.
</ParamField>

<ParamField body="max_tokens" type="integer" required>
  Maximum number of tokens to generate. This field is required in Anthropic format (unlike Chat Completions where it has a default). Set it explicitly to avoid unexpected truncation.
</ParamField>

<ParamField body="temperature" type="float">
  Sampling temperature between `0` and `1` (Anthropic range). Lower values produce more focused output.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Set to `true` to receive the response as a stream of Anthropic-format SSE events.
</ParamField>

***

## Request Examples

<CodeGroup>
  ```python Anthropic SDK (recommended) theme={null}
  import anthropic

  # Point the SDK at Piramyd — no other changes needed
  client = anthropic.Anthropic(
      api_key="sk-YOUR_KEY",
      base_url="https://api.piramyd.cloud/v1",
  )

  message = client.messages.create(
      model="claude-opus-4.8",
      system="You are a helpful coding assistant.",
      messages=[
          {"role": "user", "content": "Explain async/await in Python."}
      ],
      max_tokens=1200,
      temperature=0.2,
  )

  print(message.content[0].text)
  ```

  ```bash curl theme={null}
  curl https://api.piramyd.cloud/v1/messages \
    -H "x-api-key: sk-YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-opus-4.8",
      "system": "You are a helpful coding assistant.",
      "messages": [
        {"role": "user", "content": "Explain async/await in Python."}
      ],
      "max_tokens": 1200,
      "temperature": 0.2,
      "stream": false
    }'
  ```
</CodeGroup>

***

## Response Shape

The response follows the Anthropic Messages response format.

<ResponseField name="id" type="string">
  Unique identifier for this message, prefixed with `msg_`.
</ResponseField>

<ResponseField name="type" type="string">
  Always `"message"`.
</ResponseField>

<ResponseField name="role" type="string">
  Always `"assistant"`.
</ResponseField>

<ResponseField name="content" type="array">
  Array of content blocks generated by the model. For standard text responses, this contains one block with `type: "text"` and a `text` field.

  <Expandable title="content block fields">
    <ResponseField name="content[i].type" type="string">
      The content block type. `"text"` for standard text output; `"tool_use"` when the model is calling a tool.
    </ResponseField>

    <ResponseField name="content[i].text" type="string">
      The generated text. Present when `type` is `"text"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="string">
  The exact model ID that generated the response.
</ResponseField>

<ResponseField name="stop_reason" type="string">
  Why the model stopped generating:

  * `"end_turn"` — natural end of output
  * `"max_tokens"` — hit the `max_tokens` limit
  * `"tool_use"` — the model is requesting a tool call
</ResponseField>

<ResponseField name="usage" type="object">
  Token counts for this request.

  <Expandable title="usage fields">
    <ResponseField name="usage.input_tokens" type="integer">
      Tokens in the input (system + messages).
    </ResponseField>

    <ResponseField name="usage.output_tokens" type="integer">
      Tokens generated in the response.
    </ResponseField>
  </Expandable>
</ResponseField>

**Example response**

```json theme={null}
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "In Python, `async` and `await` are used to write asynchronous code..."
    }
  ],
  "model": "claude-opus-4.8",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 210
  }
}
```