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

# Messages API

Call the Messages API to get the model-generated response data. This endpoint is compatible with the Anthropic Messages API format — you can use the Anthropic SDK directly or the same JSON shape.

<Note>
  This page lists only the currently confirmed supported fields. Do not pass fields that are not listed here.
</Note>

## Endpoint

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

<Note>
  When using the Anthropic SDK, set `base_url` to `https://api.stepfun.ai` — the SDK will automatically append `/v1/messages`, you don't need to include `/v1` manually.
</Note>

## Request Parameters

* `model` `string` ***required***<br />Model name. Use the public model name your account has access to, e.g. `step-3.7-flash` or `step-3.5-flash`.
* `messages` `object array` ***required***<br />Conversation history; at least one message.
  <Expandable>
    * `role` `string`<br />Role name. Common values: `user`, `assistant`.
    * `content` `string or object array`<br />Plain text, or an array of Content Blocks.
        <Expandable>
          * Plain text message `string`
          * Content Block array `object array`
                <Expandable>
                  * Text block `object`
                          <Expandable>
                            * `type` `string`<br />Always `text`.
                            * `text` `string`<br />Text content.
                          </Expandable>
                  * Image block `object`
                          <Expandable>
                            * `type` `string`<br />Always `image`.
                            * `source` `object`<br />Image source. Supports URL or Base64.
                                      <Expandable>
                                        * URL: `{ "type": "url", "url": "https://..." }`
                                        * Base64: `{ "type": "base64", "media_type": "image/png", "data": "..." }`
                                      </Expandable>
                          </Expandable>
                  * Tool use block `object` (initiated by the model)
                          <Expandable>
                            * `type` `string`<br />Always `tool_use`.
                            * `id` `string`<br />Unique ID for this tool call.
                            * `name` `string`<br />Name of the tool being called.
                            * `input` `object`<br />Arguments passed to the tool.
                          </Expandable>
                  * Tool result block `object` (returned by the caller)
                          <Expandable>
                            * `type` `string`<br />Always `tool_result`.
                            * `tool_use_id` `string`<br />ID of the matching tool call.
                            * `content` `string or object array`<br />Tool execution result.
                            * `is_error` `boolean`<br />Whether the tool execution errored.
                          </Expandable>
                </Expandable>
        </Expandable>
  </Expandable>
* `max_tokens` `int` ***required***<br />Maximum number of tokens to generate; must be greater than 0.
* `system` `string or array` ***optional***<br />System prompt. Either a string or an array of text blocks.
* `tools` `object array` ***optional***<br />List of tool definitions.
  <Expandable>
    * `name` `string`<br />Tool name.
    * `description` `string`<br />Tool description — helps the model decide when to use it.
    * `input_schema` `object`<br />JSON Schema describing the tool input.
  </Expandable>
* `output_config` `object` ***optional***<br />Structured output configuration.
  <Expandable>
    * `effort` `string`<br />Controls how much reasoning the model performs. Models supporting three reasoning levels accept `low`, `medium`, `high`; `step-3.5-flash-2603` accepts only `low` and `high`.
  </Expandable>
* `stream` `boolean` ***optional***<br />Whether to stream the response; default is non-streaming.
* `temperature` `float` ***optional***<br />Sampling temperature, between 0 and 2.
* `top_p` `float` ***optional***<br />Nucleus sampling parameter, greater than 0 and at most 1.
* `top_k` `int` ***optional***<br />top-k parameter, between 0 and 500.
* `stop_sequences` `string array` ***optional***<br />Stop sequences — generation stops when any of these appear in the output.

## Response

### Non-streaming response

`Content-Type: application/json`

```json theme={null}
{
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 20,
        "output_tokens": 12
    },
    "content": [
        {
            "type": "text",
            "text": "I'm an AI assistant."
        }
    ]
}
```

**Response fields**

* `id` `string`<br />Unique message ID.
* `type` `string`<br />Object type, always `message`.
* `role` `string`<br />Role name, always `assistant`.
* `content` `object array`<br />List of content blocks. Typically `text`; in tool-calling scenarios may include `tool_use`.
* `stop_reason` `string`<br />Why generation stopped. One of `end_turn`, `tool_use`, `max_tokens`.
* `usage` `object`<br />Token usage statistics — at least `input_tokens` and `output_tokens`.

### Streaming response

`Content-Type: text/event-stream`

Streaming uses standard SSE format. Each event has an `event:` line and a `data:` line; `data:` is JSON.

Common event types: `message_start`, `content_block_start`, `content_block_delta`, `content_block_stop`, `message_delta`, `message_stop`, `ping`.

When streaming tool-call arguments, `content_block_delta.delta.type` may be `input_json_delta`.

```text theme={null}
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","model":"step-3.5-flash"}}

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

event: message_delta
data: {"type":"message_delta","stop_reason":"end_turn","usage":{"input_tokens":20,"output_tokens":12}}

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

## Examples

<Tabs>
  <Tab title="Basic chat">
    <Tabs>
      <Tab title="python">
        ```python theme={null}
        from anthropic import Anthropic

        client = Anthropic(api_key="STEP_API_KEY", base_url="https://api.stepfun.ai")

        message = client.messages.create(
            model="step-3.5-flash",
            max_tokens=1024,
            system="You are an AI chat assistant provided by StepFun. You are fluent in English, Chinese, and many other languages. You answer user questions quickly and accurately while protecting user data.",
            messages=[
                {
                    "role": "user",
                    "content": "Introduce yourself in one sentence."
                }
            ],
        )

        print(message)
        ```
      </Tab>

      <Tab title="js">
        ```js theme={null}
        import Anthropic from "@anthropic-ai/sdk";

        const client = new Anthropic({
            apiKey: "STEP_API_KEY",
            baseURL: "https://api.stepfun.ai"
        });

        async function main() {
            const message = await client.messages.create({
                model: "step-3.5-flash",
                max_tokens: 1024,
                system: "You are an AI chat assistant provided by StepFun. You are fluent in English, Chinese, and many other languages. You answer user questions quickly and accurately while protecting user data.",
                messages: [
                    {
                        role: "user",
                        content: "Introduce yourself in one sentence."
                    }
                ]
            });

            console.log(JSON.stringify(message));
        }

        main();
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        curl https://api.stepfun.ai/v1/messages \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer $STEP_API_KEY" \
          -d '{
            "model": "step-3.5-flash",
            "max_tokens": 1024,
            "system": "You are an AI chat assistant provided by StepFun. You are fluent in English, Chinese, and many other languages. You answer user questions quickly and accurately while protecting user data.",
            "messages": [
                {
                    "role": "user",
                    "content": "Introduce yourself in one sentence."
                }
            ]
        }'
        ```
      </Tab>
    </Tabs>

    ```json filename="Response" theme={null}
    {
        "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
        "type": "message",
        "role": "assistant",
        "stop_reason": "end_turn",
        "usage": {
            "input_tokens": 35,
            "output_tokens": 20
        },
        "content": [
            {
                "type": "text",
                "text": "I'm an AI chat assistant by StepFun, ready to answer your questions in English, Chinese, and other languages quickly and accurately."
            }
        ]
    }
    ```
  </Tab>

  <Tab title="Streaming response">
    <Tabs>
      <Tab title="python">
        ```python theme={null}
        from anthropic import Anthropic

        client = Anthropic(api_key="STEP_API_KEY", base_url="https://api.stepfun.ai")

        with client.messages.stream(
            model="step-3.5-flash",
            max_tokens=1024,
            messages=[
                {
                    "role": "user",
                    "content": "Introduce yourself in one sentence."
                }
            ],
        ) as stream:
            for text in stream.text_stream:
                print(text, end="", flush=True)

        print()
        ```
      </Tab>

      <Tab title="js">
        ```js theme={null}
        import Anthropic from "@anthropic-ai/sdk";

        const client = new Anthropic({
            apiKey: "STEP_API_KEY",
            baseURL: "https://api.stepfun.ai"
        });

        async function main() {
            const stream = client.messages.stream({
                model: "step-3.5-flash",
                max_tokens: 1024,
                messages: [
                    {
                        role: "user",
                        content: "Introduce yourself in one sentence."
                    }
                ]
            });

            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();
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        curl https://api.stepfun.ai/v1/messages \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer $STEP_API_KEY" \
          -d '{
            "model": "step-3.5-flash",
            "max_tokens": 1024,
            "stream": true,
            "messages": [
                {
                    "role": "user",
                    "content": "Introduce yourself in one sentence."
                }
            ]
        }'
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Using output_config.effort">
    <Tabs>
      <Tab title="python">
        ```python theme={null}
        from anthropic import Anthropic

        client = Anthropic(api_key="STEP_API_KEY", base_url="https://api.stepfun.ai")

        message = client.messages.create(
            model="step-3.7-flash",
            max_tokens=1024,
            messages=[
                {
                    "role": "user",
                    "content": "Explain reinforcement learning in three sentences."
                }
            ],
            extra_body={
                "output_config": {
                    "effort": "medium"
                }
            }
        )

        print(message)
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        curl https://api.stepfun.ai/v1/messages \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer $STEP_API_KEY" \
          -d '{
            "model": "step-3.7-flash",
            "max_tokens": 1024,
            "messages": [
                {
                    "role": "user",
                    "content": "Explain reinforcement learning in three sentences."
                }
            ],
            "output_config": {
                "effort": "medium"
            }
        }'
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>