> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/compute/aig/chat-completion/anthropic-claude/anthropic-claude-message.md).

# Chat Completion (Anthropic Protocol)

## 1. Overview

Claude is a large language model developed by Anthropic, with powerful conversational and writing capabilities. It can understand context, generate coherent text, write code, and excels at logical reasoning and analysis. It prioritizes safety and ethical guidelines and clearly identifies itself as an AI assistant. It supports multilingual communication and can handle complex tasks and long conversations.

{% hint style="success" %}
This API conforms to the Anthropic Claude interface format specification and supports all official parameters.
{% endhint %}

{% hint style="info" %}
This document only lists a subset of parameters. For the full parameter list, refer to the [official documentation](https://platform.claude.com/docs/en/api/messages/create).
{% endhint %}

**Model List:**

* `claude-sonnet-4-5-20250929`
* `claude-haiku-4-5-20251001`
* `claude-opus-4-5-20251101`
* `claude-opus-4-6`
* `claude-sonnet-4-6`
* `claude-opus-4-7`
* `claude-opus-4-8`
* `claude-sonnet-5`
* `claude-fable-5`

## 2. Request Description

* **Request Method**: `POST`
* **Request URL**:

  > `https://gateway.theturbo.ai/v1/messages`

{% hint style="info" %}
To ensure concurrent resource availability, the backend uses multi-account load balancing. To improve cache hit rates in multi-turn conversation mode, include the HTTP request header `X-Conversation-Id` with a random string in your request. The platform will preferentially route requests to the same backend account. [Reference Documentation](/api-reference/compute/aig/gateway-features/cache-optimization.md)
{% endhint %}

***

## 3. Request Parameters

### 3.1 Header Parameters

| Parameter Name | Type   | Required | Description                                                   | Example            |
| -------------- | ------ | -------- | ------------------------------------------------------------- | ------------------ |
| `Content-Type` | string | Yes      | Sets the request header type, must be `application/json`      | `application/json` |
| `Accept`       | string | Yes      | Sets the response type, recommended to use `application/json` | `application/json` |
| `x-api-key`    | string | Yes      | API\_KEY required for authentication, format: `$YOUR_API_KEY` | `$YOUR_API_KEY`    |

***

### 3.2 Body Parameters (application/json)

| Parameter Name          | Type    | Required | Description                                                                                                                                                                                                                                                                                                      | Example                                                                           |
| ----------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **model**               | string  | Yes      | The model ID to use. See the available versions listed in [Overview](#id-1.-overview), e.g. `claude-3-5-haiku-20241022`.                                                                                                                                                                                         | `claude-haiku-4-5-20251001`                                                       |
| **messages**            | array   | Yes      | List of chat messages, compatible with Anthropic format. Each object in the array contains `role` and `content`.                                                                                                                                                                                                 | `[{"role": "user","content": [{"type":"text","text":"Hello, tell me a joke."}]}]` |
| message.role            | string  | No       | Message role, possible values: `user`, `assistant`.                                                                                                                                                                                                                                                              | `user`                                                                            |
| message.content         | array   | No       | The specific content of the message.                                                                                                                                                                                                                                                                             | `[{"type":"text","text":"Hello, tell me a joke."}]`                               |
| system                  | array   | No       | System prompt.                                                                                                                                                                                                                                                                                                   | `[{"type":"text","text":"You are a friendly AI assistant"}]`                      |
| temperature             | number  | No       | Sampling temperature, value range `0～2`. Higher values produce more random output; lower values produce more focused and deterministic output.                                                                                                                                                                   | `0.7`                                                                             |
| top\_p                  | number  | No       | Another way to control the sampling distribution, value range `0～1`. Typically used as an alternative to `temperature`.                                                                                                                                                                                          | `0.9`                                                                             |
| stream                  | boolean | No       | Whether to enable streaming output. When set to `true`, returns streaming data similar to ChatGPT.                                                                                                                                                                                                               | `false`                                                                           |
| max\_tokens             | number  | No       | Maximum number of tokens that can be generated in a single response, limited by the model's context length.                                                                                                                                                                                                      | `8192`                                                                            |
| thinking                | struct  | No       | Configuration to enable Claude's extended thinking.                                                                                                                                                                                                                                                              | `{"type":"adaptive"}`                                                             |
| thinking.type           | string  | Yes      | Thinking type. Supports `enabled`, `disabled`, `adaptive`. Versions 4.7 and above support only `adaptive` and `disabled`; versions 4.5 and below support only `enabled` and `disabled`. `claude-sonnet-5` defaults to `adaptive`.                                                                                | `adaptive`                                                                        |
| thinking.budget\_tokens | number  | No       | Required when `type` is set to `enabled`. Determines how many tokens Claude may use during its internal reasoning process. A larger budget allows Claude to perform deeper analysis on complex problems, improving answer quality. The value must be greater than or equal to `1024` and less than `max_tokens`. | `1024`                                                                            |
| thinking.display        | string  | No       | When set to `summarized`, the thinking content is returned normally. When set to `omitted`, the thinking content is hidden but a signature is returned to support multi-turn conversation continuity. Versions 4.7 and above typically default to `omitted`.                                                     | `omitted`                                                                         |
| output\_config.effort   | string  | No       | Controls how much "computational effort" the model invests in reasoning tasks. Supports `low`, `medium`, `high`, `xhigh`, `max`.                                                                                                                                                                                 | `medium`                                                                          |

***

### 3.3 Supported Tools List

{% hint style="info" %}
If anthropic-beta is not empty, it means you must include the HTTP request header anthropic-beta to use that tool. Separate multiple different beta headers with commas, e.g. `anthropic-beta: computer-use-2025-01-24,context-management-2025-06-27`.
{% endhint %}

| Tool Name           | Supported Models                                                          | anthropic-beta                                      | Official Documentation                                                                               |
| ------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Bash tool`         | All models                                                                | -                                                   | [Bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool)                 |
| `Memory tool`       | Haiku series/Opus series/`claude-sonnet-4-6`                              | -                                                   | [Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)             |
| `Text editor tool`  | All models                                                                | -                                                   | [Text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool)   |
| `Tool search tool`  | Opus series                                                               | -                                                   | [Tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)   |
| `Computer use tool` | All models                                                                | `computer-use-2025-01-24`/`computer-use-2025-11-24` | [Computer use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) |
| `Compaction`        | `claude-sonnet-4-6`/`claude-opus-4-6`/`claude-opus-4-7`/`claude-opus-4-8` | `compact-2026-01-12`                                | [Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)                       |
| `Context editing`   | All models                                                                | `context-management-2025-06-27`                     | [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing)             |

***

## 4. Request Examples

### 4.1 Chat Conversation

{% tabs %}
{% tab title="HTTP" %}

```http
POST /v1/messages
Content-Type: application/json
Accept: application/json
x-api-key: $YOUR_API_KEY

{
	"model": "claude-haiku-4-5-20251001",
	"max_tokens": 4096,
	"system": [{
		"type": "text",
		"text": "You are a friendly AI assistant"
	}],
	"messages": [{
		"role": "user",
		"content": [{
			"type": "text",
			"text": "Hello, please give me an introduction to quantum mechanics"
		}]
	}]
}
```

{% endtab %}

{% tab title="Shell" %}

```sh
curl https://gateway.theturbo.ai/v1/messages \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-H "x-api-key: $YOUR_API_KEY" \
	-d "{
	\"model\": \"claude-haiku-4-5-20251001\",
	\"max_tokens\": 4096,
	\"system\": [{
		\"type\": \"text\",
		\"text\": \"You are a friendly AI assistant\"
	}],
	\"messages\": [{
		\"role\": \"user\",
		\"content\": [{
			\"type\": \"text\",
			\"text\": \"Hello, please give me an introduction to quantum mechanics\"
		}]
	}]
}"
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	apiKey := "sk-123456789012345678901234567890123456789012345678"

	client := anthropic.NewClient(
		option.WithAPIKey(apiKey),
		option.WithBaseURL("https://gateway.theturbo.ai"),
	)

	resp, err := client.Messages.New(
		context.Background(),
		anthropic.MessageNewParams{
			Model:     "claude-haiku-4-5-20251001",
			MaxTokens: 4096,
			System: []anthropic.TextBlockParam{
				{
					Type: "text",
					Text: "You are a friendly AI assistant",
				},
			},
			Messages: []anthropic.MessageParam{
				anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, please give me an introduction to quantum mechanics")),
			},
		},
	)

	if err != nil {
		fmt.Println("error:", err)
		return
	}

	for _, block := range resp.Content {
		if block.Type == "text" {
			fmt.Println("💬 Assistant reply:")
			fmt.Println(block.Text)
		}
	}

	fmt.Println("\n📊 Token usage:")
	fmt.Printf("  - Input tokens: %d\n", resp.Usage.InputTokens)
	fmt.Printf("  - Output tokens: %d\n", resp.Usage.OutputTokens)
}

```

{% endtab %}

{% tab title="Python" %}

```python
#!/usr/bin/env python3

from anthropic import Anthropic

def main():
    api_key = "sk-123456789012345678901234567890123456789012345678"

    client = Anthropic(
        api_key=api_key,
        base_url="https://gateway.theturbo.ai"
    )

    response = client.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=4096,
        system=[{
            "type": "text",
            "text": "You are a friendly AI assistant"
        }],
        messages=[{
            "role": "user",
            "content": "Hello, please give me an introduction to quantum mechanics"
        }]
    )

    for block in response.content:
        if block.type == "text":
            print("💬 Assistant reply:")
            print(block.text)

    print("\n📊 Token usage:")
    print(f"  - Input tokens: {response.usage.input_tokens}")
    print(f"  - Output tokens: {response.usage.output_tokens}")

if __name__ == "__main__":
    main()

```

{% endtab %}
{% endtabs %}

### 4.2 Prompt Caching

Prompt caching can cache the stable, unchanging prefix content in a request (such as tool definitions, system prompts, long documents, etc.), thereby reducing the cost of repeated requests and speeding up responses. For details, refer to the [official documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).

{% hint style="info" %}
This platform only supports the **Explicit cache breakpoints** approach, i.e. manually specifying cache locations by adding a `cache_control` field to specific content blocks in `tools`, `system`, and `messages`. Do not set `cache_control` at the top level of the request (the automatic caching approach is not supported).
{% endhint %}

{% hint style="info" %}
To ensure concurrent resource availability, the backend uses multi-account load balancing. To improve cache hit rates in multi-turn conversation mode, include the HTTP request header `X-Conversation-Id` with a random string in your request. The platform will preferentially route requests to the same backend account. [Reference Documentation](/api-reference/compute/aig/gateway-features/cache-optimization.md)
{% endhint %}

{% hint style="warning" %}
Since the platform backend uses multi-account resources, the longer the cache validity period, the harder it is to guarantee hitting the same backend account (affected by factors such as account quota). We recommend prioritizing the 5-minute cache (the default `ttl` value) and minimizing the use of the 1-hour cache (`ttl: "1h"`).
{% endhint %}

**`cache_control` object description:**

| Parameter Name | Type   | Required | Description                                             | Example     |
| -------------- | ------ | -------- | ------------------------------------------------------- | ----------- |
| `type`         | string | Yes      | Cache type, currently only supports `ephemeral`         | `ephemeral` |
| `ttl`          | string | No       | Cache validity period, supports `5m` (default) and `1h` | `1h`        |

```json
{ "type": "ephemeral" }              // Default validity period: 5 minutes
{ "type": "ephemeral", "ttl": "1h" } // Validity period: 1 hour
```

{% hint style="info" %}
Key usage points:

* Cache prefixes are generated in the order `tools` → `system` → `messages`. A cache breakpoint caches all content from the beginning up to and including that breakpoint.
* A maximum of **4** cache breakpoints can be set per request.
* `cache_control` can be added to: a tool in the `tools` array (usually the last tool), a text block of `system`, or a content block of `messages` (`text`, `image`, `tool_result`, etc.).
* There is a minimum cacheable token count limit (which varies by model). Below the threshold, nothing is written to the cache, and no error is raised.
* You can verify whether caching took effect via the response `usage` fields `cache_creation_input_tokens` (number of tokens written to the cache) and `cache_read_input_tokens` (number of tokens that hit the cache).
  {% endhint %}

The following example demonstrates the use of `cache_control` in three positions within the same request: tools (`tools`), the system prompt (`system`), and message content blocks (`messages`).

{% tabs %}
{% tab title="HTTP" %}

```http
POST /v1/messages
Content-Type: application/json
Accept: application/json
x-api-key: $YOUR_API_KEY

{
	"model": "claude-haiku-4-5-20251001",
	"max_tokens": 4096,
	"tools": [{
		"name": "get_weather",
		"description": "Get the weather for a specified city",
		"input_schema": {
			"type": "object",
			"properties": {
				"location": {
					"type": "string",
					"description": "City name, e.g. Beijing"
				}
			},
			"required": ["location"]
		},
		"cache_control": {
			"type": "ephemeral"
		}
	}],
	"system": [{
		"type": "text",
		"text": "You are a friendly AI assistant. Please refer to the following knowledge base to answer user questions: ... (this is a large block of stable context that needs to be cached; its length must exceed the model's minimum cacheable token count)"
	}, {
		"type": "text",
		"text": "The above is the knowledge base content.",
		"cache_control": {
			"type": "ephemeral"
		}
	}],
	"messages": [{
		"role": "user",
		"content": [{
			"type": "text",
			"text": "Hello, please give me an introduction to quantum mechanics",
			"cache_control": {
				"type": "ephemeral"
			}
		}]
	}]
}
```

{% endtab %}

{% tab title="Shell" %}

```sh
curl https://gateway.theturbo.ai/v1/messages \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-H "x-api-key: $YOUR_API_KEY" \
	-d "{
	\"model\": \"claude-haiku-4-5-20251001\",
	\"max_tokens\": 4096,
	\"tools\": [{
		\"name\": \"get_weather\",
		\"description\": \"Get the weather for a specified city\",
		\"input_schema\": {
			\"type\": \"object\",
			\"properties\": {
				\"location\": {
					\"type\": \"string\",
					\"description\": \"City name, e.g. Beijing\"
				}
			},
			\"required\": [\"location\"]
		},
		\"cache_control\": { \"type\": \"ephemeral\" }
	}],
	\"system\": [{
		\"type\": \"text\",
		\"text\": \"You are a friendly AI assistant. Please refer to the following knowledge base to answer user questions: ... (this is a large block of stable context that needs to be cached; its length must exceed the model's minimum cacheable token count)\"
	}, {
		\"type\": \"text\",
		\"text\": \"The above is the knowledge base content.\",
		\"cache_control\": { \"type\": \"ephemeral\" }
	}],
	\"messages\": [{
		\"role\": \"user\",
		\"content\": [{
			\"type\": \"text\",
			\"text\": \"Hello, please give me an introduction to quantum mechanics\",
			\"cache_control\": { \"type\": \"ephemeral\" }
		}]
	}]
}"
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	apiKey := "sk-123456789012345678901234567890123456789012345678"

	client := anthropic.NewClient(
		option.WithAPIKey(apiKey),
		option.WithBaseURL("https://gateway.theturbo.ai"),
	)

	// 1) Add cache_control on the tool (caches the tools prefix)
	weatherTool := anthropic.ToolParam{
		Name:        "get_weather",
		Description: anthropic.String("Get the weather for a specified city"),
		InputSchema: anthropic.ToolInputSchemaParam{
			Properties: map[string]any{
				"location": map[string]any{
					"type":        "string",
					"description": "City name, e.g. Beijing",
				},
			},
		},
		CacheControl: anthropic.NewCacheControlEphemeralParam(),
	}

	// 2) Add cache_control on the message content block
	userText := anthropic.NewTextBlock("Hello, please give me an introduction to quantum mechanics")
	userText.OfText.CacheControl = anthropic.NewCacheControlEphemeralParam()

	resp, err := client.Messages.New(
		context.Background(),
		anthropic.MessageNewParams{
			Model:     "claude-haiku-4-5-20251001",
			MaxTokens: 4096,
			Tools: []anthropic.ToolUnionParam{
				{OfTool: &weatherTool},
			},
			// 3) Add cache_control on the system text block
			System: []anthropic.TextBlockParam{
				{
					Type: "text",
					Text: "You are a friendly AI assistant. Please refer to the following knowledge base to answer user questions: ... (this is a large block of stable context that needs to be cached; its length must exceed the model's minimum cacheable token count)",
				},
				{
					Type:         "text",
					Text:         "The above is the knowledge base content.",
					CacheControl: anthropic.NewCacheControlEphemeralParam(),
				},
			},
			Messages: []anthropic.MessageParam{
				anthropic.NewUserMessage(userText),
			},
		},
	)

	if err != nil {
		fmt.Println("error:", err)
		return
	}

	for _, block := range resp.Content {
		if block.Type == "text" {
			fmt.Println("💬 Assistant reply:")
			fmt.Println(block.Text)
		}
	}

	// Missing fields are parsed as 0 by the SDK, so no extra nil-checking is needed
	fmt.Println("\n📊 Token usage:")
	fmt.Printf("  - Input tokens: %d\n", resp.Usage.InputTokens)
	fmt.Printf("  - Cache creation input tokens: %d\n", resp.Usage.CacheCreationInputTokens)
	fmt.Printf("  - Cache read input tokens: %d\n", resp.Usage.CacheReadInputTokens)
	fmt.Printf("  - Ephemeral 5m input tokens: %d\n", resp.Usage.CacheCreation.Ephemeral5mInputTokens)
	fmt.Printf("  - Ephemeral 1h input tokens: %d\n", resp.Usage.CacheCreation.Ephemeral1hInputTokens)
	fmt.Printf("  - Output tokens: %d\n", resp.Usage.OutputTokens)
}

```

{% endtab %}

{% tab title="Python" %}

```python
#!/usr/bin/env python3

from anthropic import Anthropic

def main():
    api_key = "sk-123456789012345678901234567890123456789012345678"

    client = Anthropic(
        api_key=api_key,
        base_url="https://gateway.theturbo.ai"
    )

    response = client.messages.create(
        model="claude-haiku-4-5-20251001",
        max_tokens=4096,
        # 1) Add cache_control on the tool (caches the tools prefix)
        tools=[{
            "name": "get_weather",
            "description": "Get the weather for a specified city",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "City name, e.g. Beijing"
                    }
                },
                "required": ["location"]
            },
            "cache_control": {"type": "ephemeral"}
        }],
        # 2) Add cache_control on the system text block
        system=[
            {
                "type": "text",
                "text": "You are a friendly AI assistant. Please refer to the following knowledge base to answer user questions: ... (this is a large block of stable context that needs to be cached; its length must exceed the model's minimum cacheable token count)"
            },
            {
                "type": "text",
                "text": "The above is the knowledge base content.",
                "cache_control": {"type": "ephemeral"}
            }
        ],
        # 3) Add cache_control on the message content block
        messages=[{
            "role": "user",
            "content": [{
                "type": "text",
                "text": "Hello, please give me an introduction to quantum mechanics",
                "cache_control": {"type": "ephemeral"}
            }]
        }]
    )

    for block in response.content:
        if block.type == "text":
            print("💬 Assistant reply:")
            print(block.text)

    usage = response.usage
    cache_creation = usage.cache_creation  # may be None

    # Cache-related fields may be empty; treat them all as 0
    print("\n📊 Token usage:")
    print(f"  - Input tokens: {usage.input_tokens}")
    print(f"  - Cache creation input tokens: {usage.cache_creation_input_tokens or 0}")
    print(f"  - Cache read input tokens: {usage.cache_read_input_tokens or 0}")
    print(f"  - Ephemeral 5m input tokens: {cache_creation.ephemeral_5m_input_tokens if cache_creation else 0}")
    print(f"  - Ephemeral 1h input tokens: {cache_creation.ephemeral_1h_input_tokens if cache_creation else 0}")
    print(f"  - Output tokens: {usage.output_tokens}")

if __name__ == "__main__":
    main()

```

{% endtab %}
{% endtabs %}

## 5. Response Example

```json
{
	"model": "claude-haiku-4-5-20251001",
	"id": "msg_bdrk_01AZpXbu4crT5R6gsYJwk6KD",
	"type": "message",
	"role": "assistant",
	"content": [{
		"type": "text",
		"text": "Quantum mechanics is a branch of physics that studies the microscopic world..."
	}],
	"stop_reason": "end_turn",
	"stop_sequence": null,
	"usage": {
		"input_tokens": 36,
		"cache_creation_input_tokens": 0,
		"cache_read_input_tokens": 0,
		"cache_creation": {
			"ephemeral_5m_input_tokens": 0,
			"ephemeral_1h_input_tokens": 0
		},
		"output_tokens": 366
	}
}
```