# 创建 AI 助手消息（v1） (/zh/api/assistant/create-assistant-message) 已废弃 assistant message v1 端点与 **AI SDK v4** 兼容。若你使用 AI SDK v5 或更高版本，请改用 [assistant message v2 端点](/zh/api/assistant/create-assistant-message-v2)。
## 与 `useChat` 集成 [#与-usechat-集成]
将 AI 助手 API 集成到你的应用中的推荐方式是使用 Vercel 的 AI SDK 提供的 `useChat` 钩子。 ```bash npm i ai@^4.1.15 ``` ```tsx 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 (
{messages.map((message) => (
{message.role === 'user' ? 'User: ' : 'Assistant: '} {message.content}
))}
); } ``` **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 个字符。 在 AI SDK 文档中查看 [useChat](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) 以了解更多详情。
## 速率限制 [#速率限制]
AI 助手 API 的限制如下： * 每个 Mintlify 组织每小时最多 10,000 次请求 * 每个 IP 每日最多 10,000 次请求 `POST /v1/assistant/{domain}/message` 为指定的 domain 生成 AI 助手的回复消息。兼容 AI SDK v4。 使用 assistant API 密钥进行身份验证。 ## OpenAPI ```json { "security": [ { "bearerAuth": [] } ], "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) 来处理响应流。" } } } } } } ```