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

# Messages API

以 Anthropic Messages API 兼容的格式调用 Step 模型，支持流式输出、工具调用、图片输入与思考深度配置。

## 请求地址

Claude Code 与 Anthropic SDK 使用配置 Base URL，并自动追加 `/v1/messages`；curl 使用完整请求地址。工具配置见 [Claude Code 接入指南](https://platform.stepfun.com/docs/zh/guides/developer/integrations/claude-code.md)。

| 通道 | 配置 Base URL | 完整请求地址 |
| - | - | - |
| 普通 API | `https://api.stepfun.com` | `POST https://api.stepfun.com/v1/messages` |
| Step Plan | `https://api.stepfun.com/step_plan` | `POST https://api.stepfun.com/step_plan/v1/messages` |

## 请求参数

请求支持以下顶层字段：

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 模型 ID，例如 `step-5-preview`、`step-3.7-flash` 或 `step-3.5-flash`。`step-router-v1` 仅可通过 [Step Plan](https://platform.stepfun.com/docs/zh/step-plan/overview.md) 通道调用，字段差异见下文。 |
| `messages` | object array | 是 | 对话消息列表，至少一条。每条消息包含 `role`（`user` / `assistant`）和 `content`（纯文本或内容块数组）。 |
| `max_tokens` | int | 是 | 最大生成 token 数，必须大于 0。 |
| `system` | string or array | 否 | 系统提示词，可传字符串或文本块数组。 |
| `tools` | object array | 否 | 工具定义列表，每项包含 `name`、`description` 和 `input_schema`（JSON Schema）。 |
| `output_config` | object | 否 | 输出配置。`effort` 控制思考深度：支持三档的模型可选 `low` / `medium` / `high`；`step-3.5-flash-2603` 兼容 `low`、`high` 两档。 |
| `stream` | boolean | 否 | 是否启用流式返回，默认非流式。 |
| `temperature` | float | 否 | 采样温度，范围为 0 到 2。 |
| `top_p` | float | 否 | Nucleus sampling 参数，大于 0 且小于等于 1。 |
| `top_k` | int | 否 | Top-k 参数，范围为 0 到 500。 |
| `stop_sequences` | string array | 否 | 停止序列列表，生成内容中遇到任意一个停止序列时停止生成。 |

### 消息内容格式

`messages` 中每条消息的 `content` 可为纯文本（string），或由以下对象组成的内容块数组：

| 块 | type | 字段 |
| - | - | - |
| 文本块 | `text` | `text`：文本内容。 |
| 图片块 | `image` | `source` 支持 URL 写法 `{"type":"url","url":"https://..."}`，或 Base64 写法 `{"type":"base64","media_type":"image/png","data":"..."}`。 |
| 工具调用块（模型发起） | `tool_use` | `id`：唯一标识；`name`：工具名；`input`：参数对象。 |
| 工具结果块（用户回传） | `tool_result` | `tool_use_id`：对应调用 ID；`content`：执行结果；`is_error`：是否出错。 |

## step-router-v1 字段限制

`step-router-v1` 仅支持 Step Plan 通道，在 `step-5-preview` 与 `step-3.7-flash` 之间自动路由。以下限制仅适用于该模型，其余字段遵循上述请求参数。

| 字段 | 调用 step-router-v1 时的行为 |
| - | - |
| `model` | 路由模型 ID 为 `step-router-v1`；无效的路由模型名称返回 HTTP 400 `request_params_invalid`。 |
| `max_tokens` | 上限为 64K |
| `messages.content` 中的图像块 / 文档块 | 不支持，使用会返回 `unsupported_content_type` |
| `tools` 中的 `web_search` | 不支持，使用会返回 `unsupported_content_type` |
| `output_config.effort` | 字段会被忽略 |

## 请求响应

### 非流式响应

`Content-Type: application/json`

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "model": "step-5-preview",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 20,
        "output_tokens": 12
    },
    "content": [
        {
            "type": "text",
            "text": "我是一个 AI 助手。"
        }
    ]
}
```

#### 响应字段说明

| 字段 | 类型 | 说明 |
| - | - | - |
| `id` | string | 消息的唯一标识。 |
| `type` | string | 对象类型，总是为 `message`。 |
| `role` | string | 角色名称，总是为 `assistant`。 |
| `model` | string | 本次响应使用的模型 ID。 |
| `content` | object array | 返回内容块列表，可能包含 `text`、`thinking` 或 `tool_use`。 |
| `stop_reason` | string | 生成停止原因，可选值为 `end_turn`、`tool_use`、`max_tokens`。 |
| `usage` | object | Token 用量统计，包含 `input_tokens` 与 `output_tokens`；缓存命中时可能包含缓存用量字段。 |

### 流式响应

`Content-Type: text/event-stream`

流式返回采用标准 SSE 格式，每个事件包含 `event:` 和 `data:` 两部分，`data:` 的内容为 JSON。

常见事件类型：`message_start`、`content_block_start`、`content_block_delta`、`content_block_stop`、`message_delta`、`message_stop`、`ping`

当返回工具调用参数时，`content_block_delta.delta.type` 可能为 `input_json_delta`。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","model":"step-5-preview","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":20,"output_tokens":1}}}

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":"你"}}

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

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":12}}

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

## 示例

将 `YOUR_STEP_API_KEY` 替换为实际密钥；使用环境变量的示例需先设置 `STEP_API_KEY`。按所用通道选择普通 API 或 Step Plan。

> [tab] 基础对话
>
> > [tab] 普通 API
> >
> > ```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > from anthropic import Anthropic
> >
> > client = Anthropic(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com")
> >
> > message = client.messages.create(
> >     model="step-5-preview",
> >     max_tokens=1024,
> >     system="你是由阶跃星辰提供的AI聊天助手，你擅长中文、英文及多种语言。在保证用户数据安全的前提下，快速精准地回答用户问题。",
> >     messages=[
> >         {
> >             "role": "user",
> >             "content": "请用一句话介绍你自己。"
> >         }
> >     ],
> > )
> >
> > print(message)
> > ```
> >
> > ```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > import Anthropic from "@anthropic-ai/sdk";
> >
> > const client = new Anthropic({
> >     apiKey: "YOUR_STEP_API_KEY",
> >     baseURL: "https://api.stepfun.com"
> > });
> >
> > async function main() {
> >     const message = await client.messages.create({
> >         model: "step-5-preview",
> >         max_tokens: 1024,
> >         system: "你是由阶跃星辰提供的AI聊天助手，你擅长中文、英文及多种语言。在保证用户数据安全的前提下，快速精准地回答用户问题。",
> >         messages: [
> >             {
> >                 role: "user",
> >                 content: "请用一句话介绍你自己。"
> >             }
> >         ]
> >     });
> >
> >     console.log(JSON.stringify(message));
> > }
> >
> > main();
> > ```
> >
> > ```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > curl https://api.stepfun.com/v1/messages \
> >   -H "Content-Type: application/json" \
> >   -H "Authorization: Bearer $STEP_API_KEY" \
> >   -d '{
> >     "model": "step-5-preview",
> >     "max_tokens": 1024,
> >     "system": "你是由阶跃星辰提供的AI聊天助手，你擅长中文、英文及多种语言。在保证用户数据安全的前提下，快速精准地回答用户问题。",
> >     "messages": [
> >         {
> >             "role": "user",
> >             "content": "请用一句话介绍你自己。"
> >         }
> >     ]
> > }'
> > ```
> >
> > ```json filename="响应示例" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > {
> >     "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
> >     "type": "message",
> >     "role": "assistant",
> >     "model": "step-5-preview",
> >     "stop_reason": "end_turn",
> >     "usage": {
> >         "input_tokens": 35,
> >         "output_tokens": 20
> >     },
> >     "content": [
> >         {
> >             "type": "text",
> >             "text": "我是阶跃星辰提供的AI聊天助手，能够用中文、英文等多种语言快速精准地回答您的问题。"
> >         }
> >     ]
> > }
> > ```
>
> > [tab] Step Plan
> >
> > ```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > import os
> > from anthropic import Anthropic
> >
> > client = Anthropic(
> >     api_key=os.environ["STEP_API_KEY"],
> >     base_url="https://api.stepfun.com/step_plan",
> > )
> >
> > message = client.messages.create(
> >     model="step-5-preview",
> >     max_tokens=1024,
> >     messages=[
> >         {
> >             "role": "user",
> >             "content": "Reply with OK."
> >         }
> >     ],
> > )
> >
> > print(message.content)
> > ```
> >
> > ```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > import Anthropic from "@anthropic-ai/sdk";
> >
> > const client = new Anthropic({
> >     apiKey: process.env.STEP_API_KEY,
> >     baseURL: "https://api.stepfun.com/step_plan"
> > });
> >
> > async function main() {
> >     const message = await client.messages.create({
> >         model: "step-5-preview",
> >         max_tokens: 1024,
> >         messages: [
> >             {
> >                 role: "user",
> >                 content: "Reply with OK."
> >             }
> >         ]
> >     });
> >
> >     console.log(message.content);
> > }
> >
> > main();
> > ```
> >
> > ```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > export STEP_API_KEY="YOUR_STEP_API_KEY"
> >
> > curl https://api.stepfun.com/step_plan/v1/messages \
> >   -H "Content-Type: application/json" \
> >   -H "Authorization: Bearer ${STEP_API_KEY}" \
> >   -d '{
> >     "model": "step-5-preview",
> >     "max_tokens": 1024,
> >     "messages": [
> >         {
> >             "role": "user",
> >             "content": "Reply with OK."
> >         }
> >     ]
> > }'
> > ```
> >
> > ```json filename="响应示例" theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > {
> >     "id": "msg_xxx",
> >     "type": "message",
> >     "role": "assistant",
> >     "model": "step-5-preview",
> >     "stop_reason": "end_turn",
> >     "usage": {
> >         "input_tokens": 20,
> >         "output_tokens": 1
> >     },
> >     "content": [
> >         {
> >             "type": "text",
> >             "text": "OK"
> >         }
> >     ]
> > }
> > ```

> [tab] 流式响应
>
> > [tab] 普通 API
> >
> > ```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > from anthropic import Anthropic
> >
> > client = Anthropic(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com")
> >
> > with client.messages.stream(
> >     model="step-5-preview",
> >     max_tokens=1024,
> >     messages=[
> >         {
> >             "role": "user",
> >             "content": "请用一句话介绍你自己。"
> >         }
> >     ],
> > ) as stream:
> >     for text in stream.text_stream:
> >         print(text, end="", flush=True)
> >
> > print()
> > ```
> >
> > ```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > import Anthropic from "@anthropic-ai/sdk";
> >
> > const client = new Anthropic({
> >     apiKey: "YOUR_STEP_API_KEY",
> >     baseURL: "https://api.stepfun.com"
> > });
> >
> > async function main() {
> >     const stream = client.messages.stream({
> >         model: "step-5-preview",
> >         max_tokens: 1024,
> >         messages: [
> >             {
> >                 role: "user",
> >                 content: "请用一句话介绍你自己。"
> >             }
> >         ]
> >     });
> >
> >     for await (const event of stream) {
> >         if (
> >             event.type === "content_block_delta" &&
> >             event.delta.type === "text_delta"
> >         ) {
> >             process.stdout.write(event.delta.text);
> >         }
> >     }
> >
> >     console.log();
> > }
> >
> > main();
> > ```
> >
> > ```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > curl https://api.stepfun.com/v1/messages \
> >   -H "Content-Type: application/json" \
> >   -H "Authorization: Bearer $STEP_API_KEY" \
> >   -d '{
> >     "model": "step-5-preview",
> >     "max_tokens": 1024,
> >     "stream": true,
> >     "messages": [
> >         {
> >             "role": "user",
> >             "content": "请用一句话介绍你自己。"
> >         }
> >     ]
> > }'
> > ```
>
> > [tab] Step Plan
> >
> > ```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > import os
> > from anthropic import Anthropic
> >
> > client = Anthropic(
> >     api_key=os.environ["STEP_API_KEY"],
> >     base_url="https://api.stepfun.com/step_plan",
> > )
> >
> > with client.messages.stream(
> >     model="step-5-preview",
> >     max_tokens=1024,
> >     messages=[
> >         {
> >             "role": "user",
> >             "content": "Reply with OK."
> >         }
> >     ],
> > ) as stream:
> >     for text in stream.text_stream:
> >         print(text, end="", flush=True)
> >
> > print()
> > ```
> >
> > ```js JavaScript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > import Anthropic from "@anthropic-ai/sdk";
> >
> > const client = new Anthropic({
> >     apiKey: process.env.STEP_API_KEY,
> >     baseURL: "https://api.stepfun.com/step_plan"
> > });
> >
> > async function main() {
> >     const stream = client.messages.stream({
> >         model: "step-5-preview",
> >         max_tokens: 1024,
> >         messages: [
> >             {
> >                 role: "user",
> >                 content: "Reply with OK."
> >             }
> >         ]
> >     });
> >
> >     for await (const event of stream) {
> >         if (
> >             event.type === "content_block_delta" &&
> >             event.delta.type === "text_delta"
> >         ) {
> >             process.stdout.write(event.delta.text);
> >         }
> >     }
> >
> >     console.log();
> > }
> >
> > main();
> > ```
> >
> > ```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > export STEP_API_KEY="YOUR_STEP_API_KEY"
> >
> > curl https://api.stepfun.com/step_plan/v1/messages \
> >   -H "Content-Type: application/json" \
> >   -H "Authorization: Bearer ${STEP_API_KEY}" \
> >   -d '{
> >     "model": "step-5-preview",
> >     "max_tokens": 1024,
> >     "stream": true,
> >     "messages": [
> >         {
> >             "role": "user",
> >             "content": "Reply with OK."
> >         }
> >     ]
> > }'
> > ```

> [tab] 使用 output\_config.effort
>
> > [tab] 普通 API
> >
> > ```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > from anthropic import Anthropic
> >
> > client = Anthropic(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com")
> >
> > message = client.messages.create(
> >     model="step-5-preview",
> >     max_tokens=1024,
> >     messages=[
> >         {
> >             "role": "user",
> >             "content": "请用三句话解释什么是强化学习。"
> >         }
> >     ],
> >     extra_body={
> >         "output_config": {
> >             "effort": "medium"
> >         }
> >     }
> > )
> >
> > print(message)
> > ```
> >
> > ```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > curl https://api.stepfun.com/v1/messages \
> >   -H "Content-Type: application/json" \
> >   -H "Authorization: Bearer $STEP_API_KEY" \
> >   -d '{
> >     "model": "step-5-preview",
> >     "max_tokens": 1024,
> >     "messages": [
> >         {
> >             "role": "user",
> >             "content": "请用三句话解释什么是强化学习。"
> >         }
> >     ],
> >     "output_config": {
> >         "effort": "medium"
> >     }
> > }'
> > ```
>
> > [tab] Step Plan
> >
> > ```python Python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > import os
> > from anthropic import Anthropic
> >
> > client = Anthropic(
> >     api_key=os.environ["STEP_API_KEY"],
> >     base_url="https://api.stepfun.com/step_plan",
> > )
> >
> > message = client.messages.create(
> >     model="step-5-preview",
> >     max_tokens=1024,
> >     messages=[
> >         {
> >             "role": "user",
> >             "content": "请用三句话解释什么是强化学习。"
> >         }
> >     ],
> >     extra_body={
> >         "output_config": {
> >             "effort": "medium"
> >         }
> >     }
> > )
> >
> > print(message)
> > ```
> >
> > ```bash cURL theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> > export STEP_API_KEY="YOUR_STEP_API_KEY"
> >
> > curl https://api.stepfun.com/step_plan/v1/messages \
> >   -H "Content-Type: application/json" \
> >   -H "Authorization: Bearer ${STEP_API_KEY}" \
> >   -d '{
> >     "model": "step-5-preview",
> >     "max_tokens": 1024,
> >     "messages": [
> >         {
> >             "role": "user",
> >             "content": "请用三句话解释什么是强化学习。"
> >         }
> >     ],
> >     "output_config": {
> >         "effort": "medium"
> >     }
> > }'
> > ```


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