Skip to main content
POST
AI 助手的消息

useChat 集成

将 AI 助手 API 集成到你的应用中的推荐方式是使用 Vercel 的 AI SDK 提供的 useChat 钩子。
Mintlify AI 助手 API 与 AI SDK v4 兼容。如果你使用 AI SDK v5 或更高版本,则必须配置自定义传输方式。
1

安装 AI SDK v4

2

使用该钩子

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 令牌。有关如何获取 API key 的详细信息,请参阅 Assistant API Key 文档

路径参数

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 hook 提供的 handleSubmit 函数来添加用户消息并处理流式响应,而不是手动定义该数组中的对象,因为这些对象包含的参数非常多。

threadId
string

一个可选的标识符,用于在多条消息之间保持会话的连续性。提供该标识符时,系统可以将后续消息关联到同一个会话线程。当 event.type === 'finish' 时,threadId 会在响应中以 event.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