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

# 创建消息

> 使用 Anthropic Messages API 创建消息。

使用 `x-api-key: $PIPELLM_API_KEY` 和 `anthropic-version: 2023-06-01`。原生 `/v1/messages` 只会路由到 Anthropic 兼容平台。

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://api.pipellm.ai/v1/messages \
    -H "Content-Type: application/json" \
    -H "x-api-key: $PIPELLM_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "你好"}]
    }'
  ```

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

  client = anthropic.Anthropic(
      api_key=os.environ["PIPELLM_API_KEY"],
      base_url="https://api.pipellm.ai",
  )
  message = client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=1024,
      messages=[{"role": "user", "content": "你好"}],
  )
  print(message.content[0].text)
  ```
</RequestExample>

<ParamField body="model" type="string" required>
  Anthropic 模型 ID，从 [`GET /v1/models`](/zh/api-reference/list-models) 选取。
</ParamField>

<ParamField body="messages" type="array" required>
  对话消息。`role` 为 `user` 或 `assistant`。

  <Expandable title="messages[]">
    <ParamField body="role" type="string" required>
      `user` 或 `assistant`。
    </ParamField>

    <ParamField body="content" type="string | array" required>
      纯文本，或内容块数组。

      <Expandable title="content blocks">
        <ParamField body="type" type="string" required>
          通常是 `text`。图片块用 `image`。
        </ParamField>

        <ParamField body="text" type="string">
          `type` 为 `text` 时必填。
        </ParamField>

        <ParamField body="source" type="object">
          `type` 为 `image` 时必填。常见为 `{ "type": "base64", "media_type": "image/png", "data": "..." }` 或 URL source。
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_tokens" type="integer" required>
  最大输出 token 数。
</ParamField>

<ParamField body="system" type="string | array">
  系统提示。
</ParamField>

<ParamField body="temperature" type="number">
  采样温度，0–1。
</ParamField>

<ParamField body="top_p" type="number">
  核采样。
</ParamField>

<ParamField body="top_k" type="integer">
  Top-k 采样。
</ParamField>

<ParamField body="stream" type="boolean">
  为 `true` 时返回 SSE。
</ParamField>

<ParamField body="stop_sequences" type="string[]">
  自定义停止序列。
</ParamField>

<ParamField body="tools" type="array">
  工具定义。见 [Tool Use](/zh/api-reference/anthropic/tool-use)。

  <Expandable title="tools[]">
    <ParamField body="name" type="string" required>
      工具名。
    </ParamField>

    <ParamField body="description" type="string">
      什么时候该调用这个工具。
    </ParamField>

    <ParamField body="input_schema" type="object" required>
      工具输入的 JSON Schema。
    </ParamField>
  </Expandable>
</ParamField>

## Endpoint

```
POST https://api.pipellm.ai/v1/messages
```

<Note>
  这条 free route 只接受 Anthropic Messages 格式请求，并只路由到 Anthropic
  兼容平台。如果你想保留 Anthropic 格式去调用 OpenAI 或 Gemini 模型，请使用
  [Anthropic Format Converter](/zh/converter/anthropic-format)。
</Note>

## 安装 SDK

<Tabs>
  <Tab title="Python">
    ```bash theme={"dark"}
    pip install anthropic
    ```
  </Tab>

  <Tab title="Node.js">
    ```bash theme={"dark"}
    npm install @anthropic-ai/sdk
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={"dark"}
    go get github.com/anthropics/anthropic-sdk-go
    ```
  </Tab>
</Tabs>

## 代码示例

<Tabs>
  <Tab title="cURL">
    ```bash theme={"dark"}
    curl https://api.pipellm.ai/v1/messages \
      -H "Content-Type: application/json" \
      -H "x-api-key: $PIPELLM_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -d @- << 'EOF'
    {
      "model": "claude-sonnet-4-5-20250929",
      "max_tokens": 1024,
      "messages": [
        {"role": "user", "content": "Why is the sky blue?"}
      ]
    }
    EOF
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"dark"}
    import os
    import anthropic

    client = anthropic.Anthropic(
      api_key=os.getenv('PIPELLM_API_KEY'),
      base_url='https://api.pipellm.ai'
    )

    message = client.messages.create(
      model='claude-sonnet-4-5-20250929',
      max_tokens=1024,
      messages=[
        {'role': 'user', 'content': 'Why is the sky blue?'}
      ]
    )

    print(message.content[0].text)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={"dark"}
    import Anthropic from '@anthropic-ai/sdk';

    const client = new Anthropic({
      apiKey: process.env.PIPELLM_API_KEY,
      baseURL: 'https://api.pipellm.ai'
    });

    const message = await client.messages.create({
      model: 'claude-sonnet-4-5-20250929',
      max_tokens: 1024,
      messages: [
        { role: 'user', content: 'Why is the sky blue?' }
      ]
    });

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

  <Tab title="Go">
    ```go theme={"dark"}
    package main

    import (
      "context"
      "os"
      "github.com/anthropics/anthropic-sdk-go"
      "github.com/anthropics/anthropic-sdk-go/option"
    )

    func main() {
      client := anthropic.NewClient(
        option.WithAPIKey(os.Getenv("PIPELLM_API_KEY")),
        option.WithBaseURL("https://api.pipellm.ai"),
      )

      message, _ := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
        Model:     anthropic.F("claude-sonnet-4-5-20250929"),
        MaxTokens: anthropic.Int(1024),
        Messages: anthropic.F([]anthropic.MessageParam{
          anthropic.NewUserMessage(anthropic.NewTextBlock("Why is the sky blue?")),
        }),
      })
    }
    ```
  </Tab>
</Tabs>

## 响应格式

```json theme={"dark"}
{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "The sky appears blue because..."}
  ],
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 50
  }
}
```

<ResponseField name="id" type="string">
  消息 ID。
</ResponseField>

<ResponseField name="type" type="string">
  固定为 `message`。
</ResponseField>

<ResponseField name="role" type="string">
  固定为 `assistant`。
</ResponseField>

<ResponseField name="content" type="array">
  输出块。文本回复是 `{ "type": "text", "text": "..." }`。工具调用是 `tool_use` 块。
</ResponseField>

<ResponseField name="stop_reason" type="string">
  `end_turn`、`max_tokens` 或 `tool_use`。
</ResponseField>

<ResponseField name="usage" type="object">
  `input_tokens` 和 `output_tokens`。
</ResponseField>

## 错误

错误信封与 [错误](/zh/api-reference/errors) 相同。原生 `/v1/messages` 在请求体不是 Anthropic 格式时也会返回 `400`。

<AccordionGroup>
  <Accordion title="400 invalid_request_error">
    缺少 `model`、`messages` 或 `max_tokens`，或协议不匹配。

    ```json theme={"dark"}
    {
      "error": {
        "type": "invalid_request_error",
        "code": "400",
        "message": "The 'model' field is required but was not provided in the request"
      }
    }
    ```
  </Accordion>

  <Accordion title="401 authentication_error">
    缺少或无效的 `x-api-key`。

    ```json theme={"dark"}
    {
      "error": {
        "type": "authentication_error",
        "code": "401",
        "message": "Incorrect API key provided. Please visit https://console.pipellm.ai/account/api-keys to find your API key."
      }
    }
    ```
  </Accordion>

  <Accordion title="402 insufficient_balance">
    ```json theme={"dark"}
    {
      "error": {
        "type": "insufficient_balance",
        "code": "402",
        "message": "Insufficient balance. Please recharge your account at https://console.pipellm.ai/billing."
      }
    }
    ```
  </Accordion>

  <Accordion title="429 rate_limit_error">
    见 [速率限制](/zh/api-reference/rate-limits)。

    ```json theme={"dark"}
    {
      "error": {
        "type": "rate_limit_error",
        "code": "429",
        "message": "Rate limit exceeded. Your current limit is 120 requests per minute (approximately 2.00 requests per second). Please visit https://console.pipellm.ai/billing to upgrade your plan for higher limits."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 相关文档

<Columns cols={3}>
  <Card title="路由与协议" icon="route" href="/zh/guides/routing-protocols">
    查看原生路由约束和 converter 路由
  </Card>

  <Card title="Anthropic 概述" icon="message" href="/zh/api-reference/anthropic/overview">
    查看 Header、模型和路由族说明
  </Card>

  <Card title="Anthropic Format Converter" icon="shuffle" href="/zh/converter/anthropic-format">
    保留 Anthropic 格式，调用其他协议族模型
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.