> ## 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.

# 创建 assistant 消息

> 针对指定的 domain，从 AI 助手生成一条回复消息。适用于 AI SDK v5 及更高版本。

<Info>
  assistant 消息 v2 端点兼容 **AI SDK v5+**。如果你正在使用 AI SDK v4，请改用 [assistant 消息 v1 端点](/zh/api/assistant/create-assistant-message)。
</Info>

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

Vercel 的 AI SDK 提供的 `useChat` hook 是在你的应用程序中集成 assistant API 的推荐方式。

<Steps>
  <Step title="安装 AI SDK">
    ```bash theme={null}
    npm i ai@^6 @ai-sdk/react
    ```
  </Step>

  <Step title="使用 hook">
    ```tsx theme={null}
    import { useState } from "react";
    import { useChat } from "@ai-sdk/react";
    import { DefaultChatTransport } from "ai";

    function MyComponent({ domain }) {
      const [input, setInput] = useState("");

      const { messages, sendMessage } = useChat({
        transport: new DefaultChatTransport({
          api: `https://api.mintlify.com/discovery/v2/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",
              },
            ],
          },
        }),
      });

      return (
        <div>
          {messages.map((message) => (
            <div key={message.id}>
              {message.role === "user" ? "User: " : "Assistant: "}
              {message.parts
                .filter((part) => part.type === "text")
                .map((part) => part.text)
                .join("")}
            </div>
          ))}
          <form
            onSubmit={(e) => {
              e.preventDefault();
              if (input.trim()) {
                sendMessage({ text: input });
                setInput("");
              }
            }}
          >
            <input value={input} onChange={(e) => setInput(e.target.value)} />
            <button type="submit">Send</button>
          </form>
        </div>
      );
    }
    ```

    **必填配置：**

    * `transport` - 使用 `DefaultChatTransport` 来配置 API 连接。
    * `body.fp` - 指纹标识符 (使用 `'anonymous'` 或唯一的用户标识符) 。
    * `body.retrievalPageSize` - 要使用的搜索结果数量 (推荐：5) 。

    **可选配置：**

    * `body.context` - 提供给 AI 助手的上下文信息数组。每个 context 对象包含：
      * `type` - `'code'` 或 `'textSelection'` 之一。
      * `value` - 代码片段或选中的文本内容。
      * `path` (可选) - 源文件或页面的路径。
      * `elementId` (可选) - 包含该 context 的 UI 元素标识符。
    * `body.currentPath` - 用户当前正在查看页面的路径。提供该字段时，AI 助手会利用此 context 提供更相关的回答。最大长度：200 个字符。
  </Step>
</Steps>

更多详情参见 AI SDK 文档中的 [useChat](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) 和 [Transport](https://ai-sdk.dev/docs/ai-sdk-ui/transport)。

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

AI 助手 API 有以下限制：

* 每个 Mintlify 组织每小时最多 10,000 个请求
* 每个 IP 地址每天最多 10,000 个请求


## OpenAPI

````yaml zh/discovery-openapi.json POST /v2/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:
  /v2/assistant/{domain}/message:
    post:
      summary: AI 助手的消息
      description: 针对指定的 domain，从 AI 助手生成一条回复消息。适用于 AI SDK v5 及更高版本。
      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
                      parts:
                        - type: text
                          text: How do I get started
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: 消息的唯一标识符。
                      role:
                        type: string
                        enum:
                          - system
                          - assistant
                          - user
                        description: 消息发送者的角色。
                      createdAt:
                        type: string
                        format: date-time
                        description: 消息创建时的时间戳。
                      parts:
                        type: array
                        items:
                          oneOf:
                            - type: object
                              description: 文本内容片段。
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - text
                                text:
                                  type: string
                              required:
                                - type
                                - text
                            - type: object
                              description: 包含可选提供方 metadata 的推理内容片段。
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - reasoning
                                text:
                                  type: string
                                providerMetadata:
                                  type: object
                                  description: 可选的、特定于提供方的 metadata。
                              required:
                                - type
                                - text
                            - type: object
                              description: 引用来源 URL 的片段。
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - source-url
                                sourceId:
                                  type: string
                                url:
                                  type: string
                                title:
                                  type: string
                                providerMetadata:
                                  type: object
                                  description: 可选的、特定于提供方的 metadata。
                              required:
                                - type
                                - sourceId
                                - url
                            - type: object
                              description: 文件附件内容片段。
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - file
                                mediaType:
                                  type: string
                                url:
                                  type: string
                                filename:
                                  type: string
                              required:
                                - type
                                - mediaType
                                - url
                            - type: object
                              description: 标记一个新步骤开始的片段。
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - step-start
                              required:
                                - type
                        description: 消息片段数组。每个片段都有一个类型以及该类型特有的字段。
                      metadata:
                        type: object
                        description: 与消息关联的可选 metadata。
                    required:
                      - id
                      - role
                      - parts
                  description: >-
                    会话中的消息数组。使用 @ai-sdk/react 包中的 useChat 钩子提供的 handleSubmit
                    函数来管理消息和流式响应。
                retrievalPageSize:
                  type: number
                  default: 5
                  description: 用于生成回答时检索的文档搜索结果数量。数值越高，可用的上下文越多，但可能增加响应时间。推荐值：5。
                filter:
                  type: object
                  default: null
                  properties:
                    version:
                      type: string
                      description: 可选的版本过滤条件。
                    language:
                      type: string
                      description: 可选的语言过滤条件。
                    groups:
                      type: array
                      items:
                        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 v5 兼容的流式响应。使用 [@ai-sdk/react 中的 useChat
                  钩子](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)
        中生成它。

````