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

# 对话 (Chat) API

> 标准化多轮对话接口，兼容 OpenAI 规范，支持 Function Calling 与多模态输入

## 说明

提供标准化的对话接口，兼容主流规范，支持多轮对话、工具调用 (Function Calling) 及多模态输入。

* **接口地址**：`POST https://api.senseaudio.cn/v1/chat/completions`
* **Content-Type**：`application/json`
* **鉴权方式**：Bearer Token，详见 [快速接入](/guides/account/quick-access)
* **流式输出**：`stream: true` 以 SSE 协议逐块返回；收到 `data: [DONE]` 标识流结束
* **模型列表**：见 [模型列表](/guides/account/model-list)
* **计费**：按输入 / 输出 token 计费，详见 [计费说明](/guides/account/billing)

## Authorizations

<ParamField header="Authorization" type="string" required>
  Bearer 鉴权头，格式为 `Bearer SENSEAUDIO_API_KEY`。
</ParamField>

## Body

<Note>`application/json`</Note>

<ParamField body="model" type="enum<string>" default="senseaudio-s2" required>
  用于补全你提示词的模型。

  可用选项：`deepseek-v4-flash`，`deepseek-v4-pro`，`doubao-seed-2-0-pro-260215`，`glm-5.1`，`glm-5.2`，`kimi-k2.6`，`minimax-m2.7`，`qwen3.6-27b`，`qwen3.6-35b-a3b`，`senseaudio-s2`，`senseaudio-s1`，`senseaudio-s2-flash`，`senseaudio-s2-lite`，`senseaudio-vl-1.0-260319`，`senseaudio-vl-lite-1.0-260319`，`sensenova-6.7-flash-lite`

  示例：`"senseaudio-s2"`
</ParamField>

<ParamField body="messages" type="object[]" required>
  包含历史对话上下文和当前输入的消息列表。

  <Expandable title="child attributes">
    <ParamField body="messages.role" type="string" required>
      发送消息的角色：`system` / `user` / `assistant` / `tool`。
    </ParamField>

    <ParamField body="messages.content" type="string | object[]" required>
      消息内容。文本形式直接传字符串；多模态形式传对象数组（如图片 URL）。
    </ParamField>

    <ParamField body="messages.name" type="string">
      参与者的名称，用于向模型提供特定的身份标识。
    </ParamField>

    <ParamField body="messages.tool_calls" type="object[]">
      仅当 `role="assistant"` 时可能出现，表示触发的工具调用列表。
    </ParamField>

    <ParamField body="messages.tool_call_id" type="string">
      仅当 `role="tool"` 时必填，表示该条执行结果对应的工具调用请求 ID。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tools" type="object[]">
  模型可调用的工具列表，主要用于 Function Calling 场景。

  <Expandable title="child attributes">
    <ParamField body="tools.type" type="string" required>
      工具类型。当前为 `"function"`。
    </ParamField>

    <ParamField body="tools.function" type="object" required>
      函数工具定义对象，包含 `name`、`description`、`parameters`（JSON Schema）。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object" default="auto">
  控制模型调用工具的行为：`none` / `auto` / `required`，或指定函数对象 `{type: 'function', function: {name: 'my_func'}}`。
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  是否开启流式响应，开启后通过 SSE 协议逐块返回。
</ParamField>

<ParamField body="stream_options" type="object">
  流式响应选项（仅 `stream=true` 时有效）。

  <Expandable title="child attributes">
    <ParamField body="stream_options.include_usage" type="boolean" default="false">
      若为 `true`，会在终止块 `[DONE]` 前返回包含 `usage` 的最后一个 chunk。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="response_format" type="object">
  输出格式：`{type: 'text'}`（默认）、`{type: 'json_object'}`（强制 JSON）。
</ParamField>

<ParamField body="max_tokens" type="integer">
  限制生成的最大 token 数量。不设置则直至自然生成完毕或达到模型上限。
</ParamField>

<ParamField body="temperature" type="number" default="1.0">
  采样温度，范围 `[0.0, 2.0]`。值越高输出越随机，建议与 `top_p` 二选一调整。
</ParamField>

<ParamField body="top_p" type="number" default="1.0">
  核采样概率阈值，范围 `[0.0, 1.0]`。
</ParamField>

<ParamField body="n" type="integer" default="1">
  为每条输入消息生成的回复选项数量。
</ParamField>

<ParamField body="stop" type="string | string[]">
  停止词序列（最多 4 个）。
</ParamField>

<ParamField body="frequency_penalty" type="number" default="0.0">
  频率惩罚系数，范围 `[-2.0, 2.0]`。
</ParamField>

<ParamField body="presence_penalty" type="number" default="0.0">
  存在惩罚系数，范围 `[-2.0, 2.0]`。
</ParamField>

<ParamField body="logit_bias" type="object">
  调整特定 token 出现的概率。键为 Token ID，值为偏差 `[-100, 100]`。
</ParamField>

<ParamField body="logprobs" type="boolean" default="false">
  是否返回输出 token 的对数概率。
</ParamField>

<ParamField body="top_logprobs" type="integer">
  返回在每个位置最可能的 N 个 token 的概率（需开启 `logprobs`，范围 `[0, 20]`）。
</ParamField>

<ParamField body="seed" type="integer">
  随机种子，用于尽可能的确定性采样。
</ParamField>

<ParamField body="user" type="string">
  最终用户的唯一标识，可用于协助监控及防滥用。
</ParamField>

## Response

`200` — `application/json`

<ResponseField name="id" type="string">
  本次请求的唯一标识符。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型。非流式为 `"chat.completion"`；流式为 `"chat.completion.chunk"`。
</ResponseField>

<ResponseField name="created" type="integer">
  生成成功的 Unix 时间戳（秒）。
</ResponseField>

<ResponseField name="model" type="string">
  实际响应的模型名称。
</ResponseField>

<ResponseField name="system_fingerprint" type="string">
  模型运行的后端配置系统指纹。
</ResponseField>

<ResponseField name="choices" type="object[]">
  模型生成的回复选项列表。

  <Expandable title="child attributes">
    <ResponseField name="choices.index" type="integer">
      在数组中的索引下标。
    </ResponseField>

    <ResponseField name="choices.finish_reason" type="string">
      停止原因：`stop` / `length` / `tool_calls` / `content_filter`。
    </ResponseField>

    <ResponseField name="choices.message" type="object">
      模型返回的消息对象（非流式）。

      <Expandable title="message fields">
        <ResponseField name="message.role" type="string">
          始终为 `"assistant"`。
        </ResponseField>

        <ResponseField name="message.content" type="string">
          文本回复内容（仅调用工具时可能为空）。
        </ResponseField>

        <ResponseField name="message.tool_calls" type="object[]">
          决定的工具调用列表，包含 `id`、`type`、`function`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="choices.delta" type="object">
      流式模式下替代 `message`，增量内容对象（含 `role` / `content` / `tool_calls` 增量）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token 消耗统计。

  <Expandable title="child attributes">
    <ResponseField name="usage.prompt_tokens" type="integer">
      提示词消耗。
    </ResponseField>

    <ResponseField name="usage.completion_tokens" type="integer">
      补全结果消耗。
    </ResponseField>

    <ResponseField name="usage.total_tokens" type="integer">
      总消耗。
    </ResponseField>
  </Expandable>
</ResponseField>

## 流式响应示例

开启 `stream: true` 时，基于 SSE 协议逐块返回：

```text theme={null}
data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1700000000,"model":"senseaudio-s2","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1700000000,"model":"senseaudio-s2","choices":[{"index":0,"delta":{"content":"黑洞"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1700000000,"model":"senseaudio-s2","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

## 错误处理

错误时返回非 200 状态码，响应体包含 `error` 对象：

<ResponseField name="error" type="object">
  错误对象。

  <Expandable title="child attributes">
    <ResponseField name="error.message" type="string">错误的人类可读描述。</ResponseField>
    <ResponseField name="error.type" type="string">错误类别（如 `invalid_request_error`）。</ResponseField>
    <ResponseField name="error.code" type="string">固定错误码的内部代号。</ResponseField>
    <ResponseField name="error.param" type="string">触发该错误的对应参数名。</ResponseField>
  </Expandable>
</ResponseField>

## 相关指南

* [文本生成介绍](/guides/llm/overview)
* [模型响应 (Responses) API](/api-reference/endpoint/llm/responses)
* [消息 (Messages)](/api-reference/endpoint/llm/messages)
* [计费说明](/guides/account/billing)


## OpenAPI

````yaml api-reference/endpoint/llm/chat.openapi.json POST /v1/chat/completions
openapi: 3.1.0
info:
  title: SenseAudio - Chat Completions
  version: 1.0.0
servers:
  - url: https://api.senseaudio.cn
    description: 生产环境
security:
  - bearerAuth: []
paths:
  /v1/chat/completions:
    post:
      tags:
        - LLM
      summary: 对话 (Chat Completions)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: senseaudio-s2
              messages:
                - role: system
                  content: 你是一个严谨的人工智能助手。
                - role: user
                  content: 你好，请解释一下什么是黑洞？
              temperature: 0.7
              stream: false
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              example:
                id: chatcmpl-1234567890
                object: chat.completion
                created: 1700000000
                model: senseaudio-s2
                system_fingerprint: fp_xxxxxx
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: 黑洞是宇宙中存在的一种天体，其引力极强...
                    finish_reason: stop
                usage:
                  prompt_tokens: 28
                  completion_tokens: 105
                  total_tokens: 133
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          enum:
            - deepseek-v4-flash
            - deepseek-v4-pro
            - doubao-seed-2-0-pro-260215
            - glm-5.1
            - glm-5.2
            - kimi-k2.6
            - minimax-m2.7
            - qwen3.6-27b
            - qwen3.6-35b-a3b
            - senseaudio-s2
            - senseaudio-s1
            - senseaudio-s2-flash
            - senseaudio-s2-lite
            - senseaudio-vl-1.0-260319
            - senseaudio-vl-lite-1.0-260319
            - sensenova-6.7-flash-lite
          default: senseaudio-s2
          example: senseaudio-s2
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - system
                  - user
                  - assistant
                  - tool
              content:
                description: 字符串或多模态对象数组
              name:
                type: string
                example: alice
              tool_calls:
                type: array
                items:
                  type: object
              tool_call_id:
                type: string
                example: call_abc123
        tools:
          type: array
          items:
            type: object
        tool_choice:
          description: 字段推断自素材文档
        stream:
          type: boolean
          default: false
        stream_options:
          type: object
        response_format:
          type: object
        max_tokens:
          type: integer
          example: 1024
        temperature:
          type: number
          example: 0.7
        top_p:
          type: number
          example: 1
    ChatCompletionResponse:
      type: object
      description: 字段推断自素材文档（兼容 OpenAI）
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
        usage:
          type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 格式：`Bearer <API_KEY>`

````