Skip to main content

Anthropic Messages API

Claude's native /v1/messages protocol is passed through the Turing Platform in fully compatible form to Claude models on Vertex AI. Compared to Chat Completions, this channel provides direct access to Claude-exclusive capabilities: fine-grained cache_control, adaptive thinking, server-side tools such as web_search_20250305, and the native content block structure.

Some domestic models (Qwen, DeepSeek, GLM, Kimi, MiniMax, Doubao Seed 2.1, etc.) can also be called via this endpoint and return the same content block structure, but Claude-exclusive capabilities described on this page (cache_control, web_search_20250305, etc.) may not be available. Refer to the Chat Models list — only models with v1/messages marked in the endpoint column are supported.

Complete Schema & Try-It

This page covers concepts, differences, and typical usage. For complete request/response fields, interactive Try-It, and multi-language code samples, see API Reference → Create a message and Count tokens.

When to choose this endpoint​

  • You need fine-grained cache control via cache_control: the Chat Completions protocol does not support this.
  • You need Claude's native thinking / server_tool_use block structure: for example, to receive signed thinking blocks directly in the response for passthrough.
  • You are already using the Anthropic Python / Node SDK: simply swap the base_url to connect.

Other options:

Overview​

ItemDetails
EndpointPOST /api/v1/messages
Protocol compatibilityAnthropic Messages API ↗
Primary use casesNative Claude conversations / function calling / extended thinking / web search / prompt caching
Supported modelsFull Claude lineup: see Model Pricing → Claude; a subset of domestic models (Alibaba DashScope, DeepSeek, Zhipu, MiniMax, KIMI, Doubao Seed 2.1, etc.) is also supported — refer to the Chat Models list for rows with v1/messages in the endpoint column
Authorization header

The Turing Platform uses Authorization: Bearer $API_KEY, not Anthropic's official x-api-key. SDKs handle this conversion automatically; take note when using cURL directly.

Capability integrations​

System prompt + cache control​

Claude's caching is explicitly declared by the caller:

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 1024,
    "system": [{
      "type": "text",
      "text": "<LARGE_INSTRUCTION>",
      "cache_control": {"type": "ephemeral"}
    }],
    "messages": [{"role": "user", "content": "..."}]
  }'

On the first request, usage.cache_creation_input_tokens is non-zero (billed at the cache write rate); on subsequent requests, usage.cache_read_input_tokens is non-zero (billed at the cache read rate, roughly 10% of the base price). Version 4.6+ supports cache_control: {"type": "ephemeral", "ttl": "1h"} to enable a 1-hour cache.

For full usage details, see Prompt Caching (Claude).

Extended thinking​

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-opus-4.8",
    "max_tokens": 16000,
    "thinking": {"type": "adaptive", "display": "summarized"},
    "messages": [{"role": "user", "content": "Explain why the sum of two even numbers is always even."}]
  }'
  • Sonnet 5: adaptive is enabled by default; enabled is not supported, but disabled can be passed to turn it off.
  • Opus 4.7 / 4.8: only type: "adaptive" is supported, disabled by default — must be explicitly passed; passing enabled returns a 400 error.
  • Opus 4.6 / Sonnet 4.6: both types are supported; Anthropic recommends adaptive.
  • 4.5 and earlier: only type: "enabled" + budget_tokens is supported.

See Thinking Model Configuration for details.

Web search (server-side tool)​

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "What is today's Shanghai Composite Index closing price?"}],
    "tools": [{
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 3
    }]
  }'

The response will contain, in sequence: a server_tool_use block → a web_search_tool_result block → a text block with citations. The billing counter usage.server_tool_use.web_search_requests is charged at $10/1K.

See Model Built-in Web Search for details.

Function calling (client-side tool)​

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "What is the weather in Shanghai today?"}],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather for a specified city",
      "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }],
    "tool_choice": {"type": "auto"}
  }'

When the model triggers a tool, it returns content: [{"type": "tool_use", "id": "...", "name": "...", "input": {...}}]. After executing the tool, send the result back as {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "...", "content": "..."}]} to continue the conversation.

Key differences from Chat Completions​

  • input_tokens counts only non-cached input: Anthropic's usage.input_tokens excludes cache_read_input_tokens; OpenAI's prompt_tokens is the total input. The platform bill is calculated on the full amount.
  • Content is a block array: multiple types including text, thinking, tool_use, server_tool_use, and web_search_tool_result. This differs semantically from OpenAI's single-string message.content.
  • max_tokens is required: when thinking is enabled, it must also be greater than thinking.budget_tokens.
  • Streaming events are more granular: message_start / content_block_start / content_block_delta (text_delta, thinking_delta, or input_json_delta) / content_block_stop / message_delta / message_stop.

For the mapping from fields to billing rates, see Billing & Usage.

turing_options​

The turing_options field (top-level request body) is a Turing Platform extension for configuring platform behaviors such as timeouts, retries, and fallback. For field definitions and values, see Timeouts, Retries & Fallback.

See also​