## 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:

```bash
Authorization: Bearer your_api_key
```

## Request Format

### Basic Request

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

### Request Parameters

| Parameter        | Type            | Required | Description                                              |
| ---------------- | --------------- | -------- | -------------------------------------------------------- |
| `model`          | string          | ✅ Yes   | Model ID or your Stack ID for multi-agent stacks         |
| `messages`       | array           | ✅ Yes   | Array of message objects with `role` and `content`       |
| `max_tokens`     | integer         | ✅ Yes   | Maximum tokens to generate (1-200000 depending on model) |
| `system`         | string or array | No       | System prompt as string or structured blocks             |
| `temperature`    | number          | No       | 0-1, controls randomness (default: 1.0)                  |
| `top_p`          | number          | No       | 0-1, nucleus sampling (default: 1.0)                     |
| `top_k`          | integer         | No       | Top-k sampling for token selection                       |
| `stop_sequences` | array           | No       | Up to 4 sequences where generation stops                 |
| `stream`         | boolean         | No       | Enable SSE streaming (default: false)                    |
| `thinking`       | object          | No       | Extended thinking configuration                          |
| `tools`          | array           | No       | Tool/function definitions for tool use                   |
| `tool_choice`    | object          | No       | Control tool selection: `auto`, `any`, `tool`, `none`    |
| `metadata`       | object          | No       | `user_id` and custom key-value pairs                     |

### Message Roles

| Role        | Description        | Required                  |
| ----------- | ------------------ | ------------------------- |
| `user`      | User input message | ✅ At least one           |
| `assistant` | Assistant response | Optional (for multi-turn) |

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

## Response Format

### Success Response

```json
{
  "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

| Field           | Type   | Description                                                  |
| --------------- | ------ | ------------------------------------------------------------ |
| `id`            | string | Unique message identifier                                    |
| `type`          | string | Always `"message"`                                           |
| `role`          | string | Always `"assistant"`                                         |
| `model`         | string | Model that generated the response                            |
| `content`       | array  | Array of content blocks (text, tool_use, etc.)               |
| `stop_reason`   | string | Why generation stopped: `end_turn`, `max_tokens`, `tool_use` |
| `stop_sequence` | string | Stop sequence matched (if any)                               |
| `usage`         | object | Token counts: `input_tokens`, `output_tokens`                |

## Advanced Features

### Extended Thinking

Control how much the model "thinks" before responding:

```json
{
  "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:**

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

**Structured format:**

```json
{
  "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:

```json
{
  "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:**

```json
{
  "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:

```bash
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:

```json
{
  "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

```json
{
  "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)

```json
{
  "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

```json
{
  "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

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

### Invalid Request

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

### Model Not Available

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

## Comparison: Anthropic vs OpenAI Format

| Feature              | Anthropic `/v1/messages`          | OpenAI `/v1/chat/completions`       |
| -------------------- | --------------------------------- | ----------------------------------- |
| **System prompt**    | Separate `system` parameter       | Message with `role: "system"`       |
| **Required params**  | `model`, `messages`, `max_tokens` | `model`, `messages`                 |
| **Token limits**     | `max_tokens` required             | `max_tokens` optional               |
| **Response format**  | `content` array with blocks       | `choices[0].message.content` string |
| **Thinking modes**   | ✅ `thinking` parameter           | ❌ Not supported                    |
| **Prompt caching**   | ✅ `cache_control` blocks         | ❌ Not supported                    |
| **Tool use schema**  | Native Anthropic tool schema      | OpenAI function calling schema      |
| **Streaming events** | SSE with typed events             | SSE with `data:` chunks             |

**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

```python
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

```typescript
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](/docs/sdks/anthropic-sdk) - Using Anthropic SDK with ModelStack
- [Chat Completions (OpenAI format)](/docs/api-reference/chat-completions) - Alternative API format
- [Models](/docs/api-reference/models) - Available models and capabilities
- [Errors](/docs/api-reference/errors) - Error codes and handling
- [Authentication](/docs/api-reference/authentication) - API key management