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

# Create Message

> Send a message to an Anthropic-compatible model and receive a response

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://router.requesty.ai/v1/messages \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_REQUESTY_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "anthropic/claude-sonnet-4-20250514",
      "max_tokens": 1024,
      "messages": [
        {
          "role": "user",
          "content": "Hello, Claude!"
        }
      ]
    }'
  ```

  ```python Python theme={"dark"}
  import anthropic

  client = anthropic.Anthropic(
      api_key="YOUR_REQUESTY_API_KEY",
      base_url="https://router.requesty.ai",
  )

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

  print(message.content[0].text)
  ```

  ```typescript TypeScript theme={"dark"}
  import Anthropic from "@anthropic-ai/sdk";

  const client = new Anthropic({
    apiKey: process.env.REQUESTY_API_KEY,
    baseURL: "https://router.requesty.ai",
  });

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

  console.log(message.content[0].text);
  ```
</RequestExample>

<ResponseExample>
  ```json Response 200 theme={"dark"}
  {
    "id": "msg_01ABC123",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm Claude, an AI assistant by Anthropic. How can I help you today?"
      }
    ],
    "model": "anthropic/claude-sonnet-4-20250514",
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 12,
      "output_tokens": 20,
      "cost": 0.000198
    }
  }
  ```
</ResponseExample>

Send a message to an Anthropic-compatible model and receive a response. This endpoint follows the Anthropic Messages API format and supports all Anthropic models as well as compatible models from other providers through Requesty's routing.

## Base URL

```
https://router.requesty.ai/v1/messages
```

## Authentication

Include your Requesty API key in the request headers using Anthropic's standard format:

```bash theme={"dark"}
x-api-key: YOUR_REQUESTY_API_KEY
```

## Headers

| Header              | Required | Description                              |
| ------------------- | -------- | ---------------------------------------- |
| `x-api-key`         | ✅        | Your Requesty API key (Anthropic format) |
| `Content-Type`      | ✅        | Must be `application/json`               |
| `anthropic-version` | ❌        | API version (defaults to `2023-06-01`)   |

## Example Request

```bash theme={"dark"}
curl https://router.requesty.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_REQUESTY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "anthropic/claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude!"
      }
    ]
  }'
```

## Model Selection

You can use any model available in the [Model Library](https://app.requesty.ai/model-list). Examples:

* **Anthropic Models:** `anthropic/claude-sonnet-4-20250514`, `anthropic/claude-3-7-sonnet`
* **OpenAI Models:** `openai/gpt-4o`, `openai/gpt-4o-mini`
* **Google Models:** `google/gemini-2.0-flash-exp`
* **Other Providers:** `mistral/mistral-large-2411`, `meta/llama-3.3-70b-instruct`

<Info>
  While this endpoint uses the Anthropic Messages format, Requesty automatically handles format conversion for non-Anthropic models, so you
  can use any supported model with this endpoint.
</Info>

## Streaming

Enable streaming responses by setting `stream: true`:

```json theme={"dark"}
{
	"model": "anthropic/claude-sonnet-4-20250514",
	"max_tokens": 1024,
	"stream": true,
	"messages": [
		{
			"role": "user",
			"content": "Write a short story"
		}
	]
}
```

## Vision Support

Send images using the content blocks format:

```json theme={"dark"}
{
	"model": "anthropic/claude-sonnet-4-20250514",
	"max_tokens": 1024,
	"messages": [
		{
			"role": "user",
			"content": [
				{
					"type": "text",
					"text": "What do you see in this image?"
				},
				{
					"type": "image",
					"source": {
						"type": "base64",
						"media_type": "image/jpeg",
						"data": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
					}
				}
			]
		}
	]
}
```

## PDF Support

You can send PDFs, encoded in base 64 format:

```json theme={"dark"}
{
	"model": "anthropic/claude-sonnet-4-20250514",
	"max_tokens": 1024,
	"messages": [
		{
			"role": "user",
			"content": [
				{
					"type": "text",
					"text": "What is in this PDF?"
				},
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": "JVBERi0=..."
                    }
				}
			]
		}
	]
}
```

## Web Search

Enable real-time web search using Anthropic's native `web_search_20250305` tool type:

```json theme={"dark"}
{
  "model": "anthropic/claude-sonnet-4-20250514",
  "max_tokens": 4096,
  "messages": [
    { "role": "user", "content": "What are the latest developments in AI?" }
  ],
  "tools": [{
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5
  }],
  "stream": true
}
```

The response includes `server_tool_use`, `web_search_tool_result`, and text blocks with `citations`. See the [Web Search guide](/features/web-search) for full response format details.

## Tool Use

Define tools that the model can call:

```json theme={"dark"}
{
	"model": "anthropic/claude-sonnet-4-20250514",
	"max_tokens": 1024,
	"tools": [
		{
			"name": "get_weather",
			"description": "Get the current weather in a given location",
			"input_schema": {
				"type": "object",
				"properties": {
					"location": {
						"type": "string",
						"description": "The city and state, e.g. San Francisco, CA"
					}
				},
				"required": ["location"]
			}
		}
	],
	"messages": [
		{
			"role": "user",
			"content": "What's the weather like in New York?"
		}
	]
}
```

## System Prompts

Include system instructions using the `system` parameter:

```json theme={"dark"}
{
	"model": "anthropic/claude-sonnet-4-20250514",
	"max_tokens": 1024,
	"system": "You are a helpful assistant that always responds in a friendly, professional manner.",
	"messages": [
		{
			"role": "user",
			"content": "Hello!"
		}
	]
}
```

## Error Handling

The API returns standard HTTP status codes:

* `200` - Success
* `400` - Bad Request (invalid parameters)
* `401` - Unauthorized (invalid API key)
* `403` - Forbidden (insufficient permissions)
* `429` - Rate Limited
* `500` - Internal Server Error

Example error response:

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

## Response Format

Successful responses follow the Anthropic Messages format:

```json theme={"dark"}
{
	"id": "msg_01ABC123",
	"type": "message",
	"role": "assistant",
	"content": [
		{
			"type": "text",
			"text": "Hello! I'm Claude, an AI assistant. How can I help you today?"
		}
	],
	"model": "anthropic/claude-sonnet-4-20250514",
	"stop_reason": "end_turn",
	"usage": {
		"input_tokens": 12,
		"output_tokens": 18,
		"cost": 0.000234
	}
}
```

The `cost` field inside `usage` is a Requesty extension and reports the USD cost of the request. It is returned by default on non-streaming responses, no extra request parameter is needed. See [Cost Tracking](/features/cost-tracking#per-request-cost-in-the-api-response).

## Key Differences from OpenAI Chat Completions

* **Authentication:** Uses `x-api-key` header instead of `Authorization: Bearer`
* **Required `max_tokens`:** Unlike OpenAI's API, the `max_tokens` parameter is required
* **Content Blocks:** Messages use content blocks for rich content (text, images, tool calls)
* **System Parameter:** System prompts are specified as a separate `system` parameter, not as a message
* **Role Restrictions:** Only `user` and `assistant` roles are supported in messages (no `system` role)

<Tip>
  For the most seamless experience with Anthropic models, use this endpoint. For broader compatibility across all providers, consider using
  the [Chat Completions endpoint](/api-reference/endpoint/chat-completions-create) instead.
</Tip>


## OpenAPI

````yaml POST /v1/messages
openapi: 3.0.3
info:
  title: Requesty API
  description: Requesty API for AI model routing and key management
  version: 1.0.0
servers:
  - url: https://api-v2.requesty.ai
    description: Management API endpoint
  - url: https://router.requesty.ai
    description: Inference router endpoint
security:
  - BearerAuth: []
paths:
  /v1/messages:
    servers:
      - url: https://router.requesty.ai
        description: Inference router endpoint
    post:
      summary: Create message
      description: Send a message to an Anthropic-compatible model and receive a response
      operationId: createMessage
      parameters:
        - name: x-api-key
          in: header
          required: true
          schema:
            type: string
          description: Your Requesty API key
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
            default: '2023-06-01'
            example: '2023-06-01'
          description: The version of the Anthropic API to use
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageRequest'
            example:
              model: anthropic/claude-sonnet-4-20250514
              max_tokens: 1024
              messages:
                - role: user
                  content: Hello, Claude!
      responses:
        '200':
          description: Message response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                id: msg_01ABC123
                type: message
                role: assistant
                content:
                  - type: text
                    text: >-
                      Hello! I'm Claude, an AI assistant by Anthropic. How can I
                      help you today?
                model: anthropic/claude-sonnet-4-20250514
                stop_reason: end_turn
                usage:
                  input_tokens: 12
                  output_tokens: 20
                  cost: 0.000198
        '400':
          description: Bad request - malformed payload or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or empty Authorization header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Payment required - organization balance exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - invalid token or model not in access list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found - provider/model not supported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Retry after the Retry-After header value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad gateway - upstream provider returned an invalid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []
components:
  schemas:
    MessageRequest:
      type: object
      required:
        - model
        - max_tokens
        - messages
      properties:
        model:
          type: string
          description: The model to use for the completion
          default: anthropic/claude-sonnet-4-20250514
          example: anthropic/claude-sonnet-4-20250514
        max_tokens:
          type: integer
          description: The maximum number of tokens to generate before stopping
          minimum: 1
          example: 1024
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicMessage'
          description: Input messages
        system:
          type: string
          description: System prompt to be used for the completion
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: Amount of randomness injected into the response
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: Use nucleus sampling
        top_k:
          type: integer
          minimum: 0
          description: Only sample from the top K options for each subsequent token
        stream:
          type: boolean
          description: >-
            Whether to incrementally stream the response using server-sent
            events
        stop_sequences:
          type: array
          items:
            type: string
          description: Custom text sequences that will cause the model to stop generating
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicTool'
          description: Definitions of tools that the model may use
        tool_choice:
          oneOf:
            - type: string
              enum:
                - auto
                - any
            - $ref: '#/components/schemas/AnthropicToolChoice'
          description: How the model should use the provided tools
    MessageResponse:
      type: object
      required:
        - id
        - type
        - role
        - content
        - model
        - stop_reason
        - usage
      properties:
        id:
          type: string
          description: Unique object identifier
        type:
          type: string
          enum:
            - message
          description: Object type
        role:
          type: string
          enum:
            - assistant
          description: Conversational role of the generated message
        content:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicContentBlock'
          description: Content generated by the model
        model:
          type: string
          description: The model that handled the request
        stop_reason:
          type: string
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
            - tool_use
          description: The reason that we stopped
        stop_sequence:
          type: string
          description: Which custom stop sequence was generated
        usage:
          $ref: '#/components/schemas/AnthropicUsage'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - origin
            - message
          properties:
            origin:
              type: string
              enum:
                - router
                - provider
              description: >-
                Whether the error originated from Requesty's router or an
                upstream provider.
            message:
              type: string
              description: Human-readable error description.
    AnthropicMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
          description: The role of the messages author
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicContentBlock'
          description: The contents of the message
    AnthropicTool:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - custom
            - web_search_20250305
          description: >-
            The type of tool. Use `custom` (default, may be omitted) for
            user-defined tools with `name`, `description`, and `input_schema`.
            Use `web_search_20250305` to enable native Anthropic web search.
          default: custom
        name:
          type: string
          description: >-
            The tool name. Required for `custom` tools. For
            `web_search_20250305`, set to `web_search`.
        description:
          type: string
          description: 'For `custom` tools: describes when the model should use this tool.'
        input_schema:
          type: object
          description: 'For `custom` tools: JSON schema for the tool input.'
        max_uses:
          type: integer
          description: >-
            For `web_search_20250305`: maximum number of web searches the model
            may perform.
          minimum: 1
    AnthropicToolChoice:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - tool
        name:
          type: string
    AnthropicContentBlock:
      oneOf:
        - $ref: '#/components/schemas/AnthropicTextBlock'
        - $ref: '#/components/schemas/AnthropicImageBlock'
        - $ref: '#/components/schemas/AnthropicToolUseBlock'
        - $ref: '#/components/schemas/AnthropicToolResultBlock'
    AnthropicUsage:
      type: object
      required:
        - input_tokens
        - output_tokens
      properties:
        input_tokens:
          type: integer
          description: The number of input tokens which were used
        output_tokens:
          type: integer
          description: The number of output tokens which were used
    AnthropicTextBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
    AnthropicImageBlock:
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          enum:
            - image
        source:
          $ref: '#/components/schemas/AnthropicImageSource'
    AnthropicToolUseBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - tool_use
        id:
          type: string
        name:
          type: string
        input:
          type: object
    AnthropicToolResultBlock:
      type: object
      required:
        - type
        - tool_use_id
      properties:
        type:
          type: string
          enum:
            - tool_result
        tool_use_id:
          type: string
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicContentBlock'
        is_error:
          type: boolean
    AnthropicImageSource:
      type: object
      required:
        - type
        - media_type
        - data
      properties:
        type:
          type: string
          enum:
            - base64
        media_type:
          type: string
          enum:
            - image/jpeg
            - image/png
            - image/gif
            - image/webp
        data:
          type: string
          description: Base64 encoded image data
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````