跳转到主要内容
POST
/
v1
/
assistant
/
{domain}
/
message
AI 助手消息 v1
curl --request POST \
  --url https://api.mintlify.com/discovery/v1/assistant/{domain}/message \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fp": "<string>",
  "messages": [
    {
      "id": "foobar",
      "role": "user",
      "content": "how do i get started",
      "parts": [
        {
          "type": "text",
          "text": "How do I get started"
        }
      ]
    }
  ],
  "threadId": null,
  "retrievalPageSize": 5,
  "filter": null
}
'
{}
已废弃
assistant message v1 端点与 AI SDK v4 兼容。若你使用 AI SDK v5 或更高版本，请改用 assistant message v2 端点。

​
与 useChat 集成

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

安装 AI SDK v4

npm i ai@^4.1.15
2

使用该钩子

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 元素的标识符。
在 AI SDK 文档中查看 useChat 以了解更多详情。

​
速率限制

AI 助手 API 的限制如下：
  • 每个 key 每月最多使用 10,000 次
  • 每个 Mintlify 组织每小时最多 10,000 次请求
  • 每个 IP 每日最多 10,000 次请求

授权

​
Authorization
string
header
必填

Authorization 请求头需要携带 Bearer 令牌。请使用以 mint_dsc_ 为前缀的 AI 助手 API 密钥。它是一个可以安全用于客户端代码的公用密钥。你可以在控制台的 API 密钥页面 中生成它。

路径参数

​
domain
string
必填

在你的 domain.mintlify.app URL 中使用的 domain 标识符。你可以在控制台 URL 的末尾找到它。例如，在 dashboard.mintlify.com/organization/domain 中，domain 标识符为 domain。

请求体

application/json
​
fp
string
必填

用于会话跟踪的指纹标识符。对匿名用户使用 anonymous，或提供唯一的用户标识符。

​
messages
object[]
必填

会话中的消息数组。在前端，你通常会希望使用 @ai-sdk 包中 useChat 钩子提供的 handleSubmit 函数来追加用户消息并处理流式响应，而不是在这个数组里手动定义对象，因为这些对象包含的参数非常多。

​
threadId
string

一个可选的标识符，用于在多条消息之间保持会话的连续性。提供该标识符后，系统可以将后续消息关联到同一个会话线程。当 event.type === 'finish' 时，响应中会通过 event.threadId 字段返回该 threadId。

​
retrievalPageSize
number
默认值:5

用于生成回复的文档搜索结果数量。数值越高可提供的上下文越多，但可能增加响应时间。推荐值：5。

​
filter
object

用于搜索的可选筛选条件。

响应

200 - application/json

消息生成成功。

响应对象，其中的数据流部分会根据指定的状态码、响应头和内容进行格式化。更多信息请参阅 AI SDK 文档：ai-sdk.dev/docs/ai-sdk-ui/streaming-data。使用 AI SDK 提供的 useChat Hook 来处理响应流。