> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 AI 助手消息（v1）

> 为指定的 domain 生成 AI 助手的回复消息。兼容 AI SDK v4。

<Badge color="orange">已废弃</Badge>

<Info>
  assistant message v1 端点与 **AI SDK v4** 兼容。若你使用 AI SDK v5 或更高版本，请改用 [assistant message v2 端点](/zh/api/assistant/create-assistant-message-v2)。
</Info>

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

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

<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.PUBLIC_MINTLIFY_ASSISTANT_KEY}`,
        },
        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 元素的标识符。
    * `body.currentPath` - 用户当前正在查看页面的路径。提供后，AI 助手会利用该上下文提供更相关的回答。最大长度：200 个字符。
  </Step>
</Steps>

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

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

AI 助手 API 的限制如下：

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


## OpenAPI

````yaml zh/discovery-openapi.json POST /v1/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
security:
  - bearerAuth: []
paths:
  /v1/assistant/{domain}/message:
    post:
      summary: AI 助手消息 v1
      description: 为指定的 domain 生成 AI 助手的回复消息。兼容 AI SDK v4。
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: >-
            在你的 `domain.mintlify.site` 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' 时，响应中会通过 event.threadId 字段返回该
                    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 钩子提供的 handleSubmit
                    函数来追加用户消息并处理流式响应，而不是在这个数组里手动定义对象，因为这些对象包含的参数非常多。
                retrievalPageSize:
                  type: number
                  default: 5
                  description: 用于生成回复的文档搜索结果数量。数值越高可提供的上下文越多，但可能增加响应时间。推荐值：5。
                filter:
                  type: object
                  default: null
                  properties:
                    version:
                      type: string
                      description: 可选的版本筛选器。
                    language:
                      type: string
                      description: 可选的语言筛选器。
                  description: 用于搜索的可选筛选条件。
                context:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - code
                          - textSelection
                        description: 所提供上下文的类型。
                      value:
                        type: string
                        description: 代码片段或选中的文本内容。
                      path:
                        type: string
                        description: 指向源文件或页面的可选路径。
                      elementId:
                        type: string
                        description: 承载该上下文的 UI 元素的可选标识符。
                    required:
                      - type
                      - value
                  description: 用于传递给 AI 助手的可选上下文信息数组。
                currentPath:
                  type: string
                  description: 用户当前正在查看的页面路径。若提供，AI 助手会利用该上下文给出更相关的回答。最大长度：200 个字符。
      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 令牌。请使用以 `mint_dsc_` 为前缀的 AI 助手 API
        密钥。它是一个可以安全用于客户端代码的公用密钥。你可以在控制台的 [API
        密钥页面](https://dashboard.mintlify.com/settings/organization/api-keys)
        中生成它。

````