Messages (Anthropic)

Overview#

The /v1/messages endpoint provides native Anthropic API format support. Use this endpoint when you want to leverage Anthropic-specific features like extended thinking, prompt caching, or when integrating with tools built for the Claude API.

Why Use Anthropic Format?#

Use Anthropic format when you need:

• Extended thinking modes (budget control, adaptive thinking)
• Prompt caching for cost optimization
• Native tool use with Anthropic's schema
• Compatibility with existing Claude API integrations

Use OpenAI format when you need:

• Drop-in replacement for OpenAI API
• Compatibility with OpenAI SDK and tools
• Simpler request/response structure

Both formats work with all ModelStack models (Claude, GPT, Gemini, etc.) - the format is just a different way to structure requests.

Endpoint#

POST https://api.modelstack.cc/v1/messages

Authentication#

Include your API key in the Authorization header:

Authorization: Bearer your_api_key

Request Format#

Basic Request#

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ]
}

Request Parameters#

Message Roles#

Note: Unlike OpenAI format, Anthropic format uses system parameter separately instead of a system role in messages.

Response Format#

Success Response#

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

Response Fields#

Advanced Features#

Extended Thinking#

Control how much the model "thinks" before responding:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "messages": [
    {
      "role": "user",
      "content": "Solve this complex math problem: ..."
    }
  ],
  "thinking": {
    "type": "enabled",
    "budget_tokens": 5000
  }
}

Thinking Modes:

• enabled - Extended thinking with token budget
• disabled - No extended thinking (faster, cheaper)
• adaptive - Model decides when to think deeply

Budget Tokens:

• 1024-4999 - Medium thinking
• 5000-9999 - High thinking
• 10000+ - Extra-high thinking (normalized to 9999)

System Prompts#

String format:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a helpful coding assistant.",
  "messages": [...]
}

Structured format:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "You are a helpful coding assistant."
    }
  ],
  "messages": [...]
}

Tool Use#

Define functions the model can call:

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What's the weather in San Francisco?"
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name"
          }
        },
        "required": ["location"]
      }
    }
  ],
  "tool_choice": {
    "type": "auto"
  }
}

Tool Choice Options:

• {"type": "auto"} - Model decides whether to use tools
• {"type": "any"} - Must use at least one tool
• {"type": "tool", "name": "tool_name"} - Must use specific tool
• {"type": "none"} - Never use tools (text response only)

Tool Use Response:

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_xyz789",
      "name": "get_weather",
      "input": {
        "location": "San Francisco"
      }
    }
  ],
  "stop_reason": "tool_use",
  "usage": {...}
}

Streaming#

Enable SSE streaming for real-time responses:

curl https://api.modelstack.cc/v1/messages \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "Write a haiku"}
    ]
  }'

Stream Events:

event: message_start
data: {"type":"message_start","message":{"id":"msg_123",...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Cherry"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" blossoms"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}

Using Model Stacks#

Use multi-agent stacks with Anthropic format:

{
  "model": "code-review-strict",
  "max_tokens": 4096,
  "messages": [
    {
      "role": "user",
      "content": "Review this code:\n\nfunction add(a, b) { return a + b }"
    }
  ]
}

The stack's coordinator and specialists will collaborate to generate the response.

Examples#

Multi-Turn Conversation#

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "What is 2+2?"
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "2 + 2 = 4"
        }
      ]
    },
    {
      "role": "user",
      "content": "What about 3+3?"
    }
  ]
}

Vision (Image Understanding)#

{
  "model": "gpt-4o",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ]
}

With Temperature Control#

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "temperature": 0.3,
  "messages": [
    {
      "role": "user",
      "content": "Generate a random creative story."
    }
  ]
}

Temperature Guide:

• 0.0-0.3 - Focused, deterministic (code, analysis)
• 0.4-0.7 - Balanced creativity (general use)
• 0.8-1.0 - High creativity (brainstorming, stories)

Error Responses#

Rate Limit Exceeded#

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Try again in 30 seconds."
  }
}

Invalid Request#

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required"
  }
}

Model Not Available#

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Model 'invalid-model' not found"
  }
}

Comparison: Anthropic vs OpenAI Format#

When to use each:

• Use Anthropic format for advanced Claude features (thinking, caching, native tools)
• Use OpenAI format for simplicity and broader tool compatibility
• Both formats work with all ModelStack models (not just Claude or GPT)

SDK Support#

Anthropic Python SDK#

from anthropic import Anthropic

client = Anthropic(
    api_key="your_modelstack_api_key",
    base_url="https://api.modelstack.cc"
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(message.content[0].text)

Anthropic TypeScript SDK#

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  apiKey: 'your_modelstack_api_key',
  baseURL: 'https://api.modelstack.cc',
})

const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello, Claude!' }],
})

console.log(message.content[0].text)

Best Practices#

Token Management#

1. Always set max_tokens - Required parameter, prevents runaway costs
2. Monitor token usage - Check usage in response to track spending
3. Use appropriate limits - Short answers: 512, long: 4096, max: model limit

Thinking Modes#

1. Use adaptive for general tasks - Model decides when deep thinking helps
2. Use high budget for complex problems - Math, reasoning, analysis
3. Disable for simple queries - Faster responses, lower cost

System Prompts#

1. Be specific - Clear instructions improve quality
2. Use structured format for complex prompts - Multiple text blocks with cache control
3. Keep it concise - Long system prompts increase cost per request

Error Handling#

1. Handle rate limits gracefully - Implement exponential backoff
2. Validate max_tokens - Ensure it's within model limits
3. Check stop_reason - Handle tool_use, max_tokens, end_turn differently

Related Documentation#

• Anthropic SDK Guide - Using Anthropic SDK with ModelStack
• Chat Completions (OpenAI format) - Alternative API format
• Models - Available models and capabilities
• Errors - Error codes and handling
• Authentication - API key management