> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 助手的消息

> 为指定的 domain 生成一条来自 AI 助手的回复消息。

<div id="integration-with-usechat">
  ## 与 `useChat` 集成
</div>

将 AI 助手 API 集成到你的应用中的推荐方式是使用 Vercel 的 AI SDK 提供的 `useChat` 钩子。

<Note>
  Mintlify AI 助手 API 与 **AI SDK v4** 兼容。如果你使用 AI SDK v5 或更高版本，则必须配置自定义传输方式。
</Note>

<Steps>
  <Step title="安装 AI SDK v4">
    ```bash theme={null}
    npm i ai@^4.1.15
    ```
  </Step>

  <Step title="使用该钩子">
    ```tsx theme={null}
    import { useChat } from 'ai/react';

    function MyComponent({ domain }) {
      const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
        api: `https://api.mintlify.com/discovery/v1/assistant/${domain}/message`,
        headers: {
          'Authorization': `Bearer ${process.env.MINTLIFY_TOKEN}`,
        },
        body: {
          fp: 'anonymous',
          retrievalPageSize: 5,
          context: [
            {
              type: 'code',
              value: 'const example = "code snippet";',
              elementId: 'code-block-1',
            },
          ],
        },
        streamProtocol: 'data',
        sendExtraMessageFields: true,
      });

      return (
        <div>
          {messages.map((message) => (
            <div key={message.id}>
              {message.role === 'user' ? 'User: ' : 'Assistant: '}
              {message.content}
            </div>
          ))}
          <form onSubmit={handleSubmit}>
            <input value={input} onChange={handleInputChange} />
            <button type="submit">Send</button>
          </form>
        </div>
      );
    }
    ```

    **Mintlify 的必备配置：**

    * `streamProtocol: 'data'` - 流式响应所必需。
    * `sendExtraMessageFields: true` - 发送消息 metadata 所必需。
    * `body.fp` - 指纹标识符（使用 `'anonymous'` 或某个用户标识符）。
    * `body.retrievalPageSize` - 要使用的搜索结果数量（推荐：5）。

    **可选配置：**

    * `body.context` - 提供给 AI 助手的上下文信息数组。每个 context 对象包含：
      * `type` - `'code'` 或 `'textSelection'` 之一。
      * `value` - 代码片段或选中的文本内容。
      * `elementId`（可选）- 包含该 context 的 UI 元素的标识符。
  </Step>
</Steps>

在 AI SDK 文档中查看 [useChat](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) 以了解更多详情。

<div id="rate-limits">
  ## 速率限制
</div>

AI 助手 API 的限制如下：

* 每个 key 每月最多使用 10,000 次
* 每个 Mintlify 组织每小时最多 10,000 次请求
* 每个 IP 每日最多 10,000 次请求


## OpenAPI

````yaml zh/discovery-openapi.json post /assistant/{domain}/message
openapi: 3.0.1
info:
  title: Mintlify Assistant API
  description: 用于将 Mintlify 的探索功能集成到你的产品中的 API。
  version: 1.0.0
servers:
  - url: https://api.mintlify.com/discovery/v1
security:
  - bearerAuth: []
paths:
  /assistant/{domain}/message:
    post:
      summary: AI 助手的消息
      description: 为指定的 domain 生成一条来自 AI 助手的回复消息。
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: >-
            来自你的 `domain.mintlify.app` URL 的 domain 标识符。可以在控制台 URL
            的末尾找到。例如，`dashboard.mintlify.com/organization/domain` 的 domain 标识符就是
            `domain`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - fp
                - messages
              properties:
                fp:
                  type: string
                  description: 用于跟踪会话会话的指纹标识符。对于匿名用户请使用 `anonymous`，或为用户提供唯一的用户标识符。
                threadId:
                  default: null
                  type: string
                  description: >-
                    一个可选的标识符，用于在多条消息之间保持会话的连续性。提供该标识符时，系统可以将后续消息关联到同一个会话线程。当
                    event.type === 'finish' 时，threadId 会在响应中以 event.threadId
                    的形式返回。
                messages:
                  type: array
                  default:
                    - id: foobar
                      role: user
                      content: how do i get started
                      parts:
                        - type: text
                          text: How do I get started
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: 消息的唯一标识
                      role:
                        type: string
                        enum:
                          - system
                          - assistant
                          - data
                          - user
                        description: 消息发送方的角色
                      createdAt:
                        type: string
                        format: date-time
                        description: 消息创建时间戳
                      content:
                        type: string
                        description: 消息内容
                      annotations:
                        type: array
                        items: {}
                        description: 消息的可选注释数组
                      parts:
                        type: array
                        items:
                          oneOf:
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - text
                                text:
                                  type: string
                              required:
                                - type
                                - text
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - reasoning
                                reasoning:
                                  type: string
                                details:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - text
                                          text:
                                            type: string
                                          signature:
                                            type: string
                                        required:
                                          - type
                                          - text
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - redacted
                                          data:
                                            type: string
                                        required:
                                          - type
                                          - data
                              required:
                                - type
                                - reasoning
                                - details
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - step-start
                              required:
                                - type
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - source
                                source:
                                  type: object
                                  properties:
                                    sourceType:
                                      type: string
                                      enum:
                                        - url
                                    id:
                                      type: string
                                    url:
                                      type: string
                                    title:
                                      type: string
                                  required:
                                    - sourceType
                                    - id
                                    - url
                              required:
                                - type
                                - source
                            - type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - tool-invocation
                                toolInvocation:
                                  oneOf:
                                    - type: object
                                      properties:
                                        state:
                                          type: string
                                          enum:
                                            - partial-call
                                        step:
                                          type: number
                                        toolCallId:
                                          type: string
                                        toolName:
                                          type: string
                                        args: {}
                                      required:
                                        - state
                                        - toolCallId
                                        - toolName
                                        - args
                                    - type: object
                                      properties:
                                        state:
                                          type: string
                                          enum:
                                            - call
                                        step:
                                          type: number
                                        toolCallId:
                                          type: string
                                        toolName:
                                          type: string
                                        args: {}
                                      required:
                                        - state
                                        - toolCallId
                                        - toolName
                                        - args
                                    - type: object
                                      properties:
                                        state:
                                          type: string
                                          enum:
                                            - result
                                        step:
                                          type: number
                                        toolCallId:
                                          type: string
                                        toolName:
                                          type: string
                                        args: {}
                                        result: {}
                                      required:
                                        - state
                                        - toolCallId
                                        - toolName
                                        - args
                                        - result
                              required:
                                - type
                                - toolInvocation
                        description: 包含文本、推理、来源和工具调用等不同类型消息片段的数组
                      experimental_attachments:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            contentType:
                              type: string
                            url:
                              type: string
                          required:
                            - url
                        description: 消息的可选实验性附件数组
                    required:
                      - id
                      - role
                      - content
                      - parts
                  description: >-
                    会话中的消息数组。在前端开发中，你通常会希望使用 @ai-sdk 包中 useChat hook 提供的
                    handleSubmit 函数来添加用户消息并处理流式响应，而不是手动定义该数组中的对象，因为这些对象包含的参数非常多。
                retrievalPageSize:
                  type: number
                  default: 5
                  description: 用于生成回复的文档搜索结果条数。数值越大，可提供的上下文越丰富，但可能会增加响应时间。推荐值：5。
                filter:
                  type: object
                  default: null
                  properties:
                    version:
                      type: string
                      description: 可选版本筛选
                    language:
                      type: string
                      description: （可选）语言过滤器
                  description: 搜索的可选筛选项
      responses:
        '200':
          description: 消息已成功生成
          content:
            application/json:
              schema:
                type: object
                description: >-
                  响应对象会以指定的状态码、响应头和内容，流式传输格式化的数据片段。这与 AI SDK 文档中说明的预期行为一致，详见
                  [ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data)。与其自行编写解析器，建议按该文档使用
                  ai-sdk 提供的 [useChat
                  hook](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat)。
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization 头需要携带 Bearer 令牌。有关如何获取 API key 的详细信息，请参阅 [Assistant API
        Key 文档](/api/introduction#assistant-api-key)。

````