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

# Claude Native /v1/messages API — Caching and Thinking

> Call Claude via POST /v1/messages using the Anthropic SDK and KiosAPI base URL. Supports prompt caching, PDF analysis, extended thinking, and streaming.

KiosAPI supports Claude's native `/v1/messages` endpoint format — use it directly with the Anthropic SDK to get full access to prompt caching and extended thinking. Prompt caching lets you mark large, repeated blocks of context (such as lengthy PDFs or system prompts) so they are cached server-side and reused across requests, significantly reducing both latency and cost.

<Tip>
  The native format only lists commonly used parameters. For the complete parameter reference, see the [Claude official documentation](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching).
</Tip>

## Supported Models

Claude native format supports models with the `cld-` or `claude-` prefix. It also supports `kimi-k2-0711-preview`, `qwen3-coder-plus`, and `glm-4.5+`.

## Request

**POST** `https://kiosapi.com/v1/messages`

### Headers

| Header              | Required | Description        |
| ------------------- | -------- | ------------------ |
| `Content-Type`      | Yes      | `application/json` |
| `x-api-key`         | Yes      | `sk-xxx`           |
| `anthropic-version` | Yes      | `2023-06-01`       |

### Request Body

<ParamField body="model" type="string" required>
  Claude model name (e.g. `claude-sonnet-4-6`).
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects forming the conversation.

  <Expandable title="messages properties">
    <ParamField body="messages[].role" type="string" required>
      Role of the message author: `user` or `assistant`.
    </ParamField>

    <ParamField body="messages[].content" type="string | array" required>
      The message content. Pass a plain string for text-only messages, or an array of content objects for multimodal input such as PDFs and images.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="number">
  Maximum number of tokens to generate in the response.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between 0 and 2.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling. Use as an alternative to `temperature`.
</ParamField>

<ParamField body="top_k" type="integer">
  Only sample from the top K options for each subsequent token.
</ParamField>

<ParamField body="stream" type="boolean">
  Set to `true` to stream the response using server-sent events.
</ParamField>

<ParamField body="tools" type="object">
  Function calling tools available to the model.
</ParamField>

<ParamField body="thinking" type="object">
  Extended thinking configuration. Available on `claude-3-7-sonnet` only.
</ParamField>

### Content Types for PDF and Image Analysis

When passing `content` as an array, each element uses one of the following structures:

| Type                  | Sub-type | Fields                                                      | Description            |
| --------------------- | -------- | ----------------------------------------------------------- | ---------------------- |
| `image` or `document` | base64   | `source.type: "base64"`, `source.data`, `source.media_type` | Base64-encoded file    |
| `image` or `document` | url      | `source.type: "url"`, `source.url`                          | File accessible by URL |
| `text`                | —        | `text`                                                      | Plain text prompt      |

### Cache Control

To cache a file or block of content across multiple requests, add a `cache_control` field to the content object. This is especially useful for large PDFs or system prompts you send repeatedly:

```json theme={null}
{
  "type": "document",
  "source": {
    "type": "base64",
    "data": "JVBERi0xLjQK...",
    "media_type": "application/pdf"
  },
  "cache_control": {
    "type": "ephemeral"
  }
}
```

### Examples

<Tabs>
  <Tab title="cURL (Chat)">
    ```bash theme={null}
    curl https://kiosapi.com/v1/messages \
      -H "Content-Type: application/json" \
      -H "x-api-key: sk-xxx" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-sonnet-4-6",
        "messages": [
          {
            "role": "user",
            "content": "Hello, who are you?"
          }
        ],
        "max_tokens": 1688,
        "temperature": 0.5,
        "stream": false
      }'
    ```
  </Tab>

  <Tab title="Python (PDF with Caching)">
    ```python theme={null}
    import anthropic

    client = anthropic.Anthropic(
        api_key="sk-xxx",
        base_url="https://kiosapi.com"
    )

    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1000,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "Summarize this document"
                    },
                    {
                        "type": "document",
                        "source": {
                            "type": "url",
                            "url": "https://example.com/document.pdf"
                        },
                        "cache_control": {"type": "ephemeral"}
                    }
                ]
            }
        ]
    )

    print(response.content[0].text)
    ```
  </Tab>

  <Tab title="Python (Extended Thinking)">
    ```python theme={null}
    response = client.messages.create(
        model="claude-3-7-sonnet-20250219",
        max_tokens=8000,
        thinking={
            "type": "enabled",
            "budget_tokens": 4000
        },
        messages=[{"role": "user", "content": "Solve this complex problem..."}]
    )
    ```
  </Tab>
</Tabs>

## Response

```json theme={null}
{
  "id": "msg_014AoBefsejHUjbdRntn7euw",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! I'm Claude, an AI assistant. How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-6",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 38
  }
}
```

### Response Fields

<ResponseField name="id" type="string">
  Unique message identifier.
</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 in the response.

  <Expandable title="content properties">
    <ResponseField name="content[].type" type="string">
      Content block type, e.g. `"text"`.
    </ResponseField>

    <ResponseField name="content[].text" type="string">
      The text of the response.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<ResponseField name="stop_reason" type="string">
  Reason the model stopped generating. One of `end_turn`, `max_tokens`, or `tool_use`.
</ResponseField>

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

  <Expandable title="usage properties">
    <ResponseField name="usage.input_tokens" type="integer">
      Number of input tokens consumed.
    </ResponseField>

    <ResponseField name="usage.output_tokens" type="integer">
      Number of output tokens generated.
    </ResponseField>
  </Expandable>
</ResponseField>