---
title: "Chat API"
description: "通过 chat completion 和多轮对话与你的 mind 交互。"
---

# Chat API

向你的 mind 发送消息并接收 AI 生成的回复。Chat API 同时支持无状态 completion 和带自动历史管理的有状态多轮对话。

## 有状态 Chat(推荐)

创建持久化对话,服务端自动管理历史、上下文压缩和滚动摘要。无需在每次请求中发送完整的消息历史。

### 创建 Chat

创建一个绑定到某个 mind 的新有状态对话。

**Endpoint:** `POST /api/v1/chats`

必须且只能提供一种非空选择：`mindId`、`mindIds` 或 `audienceIds`。混合选择返回 `400`；空的可选数组不会覆盖单个 Mind。UUID 不区分大小写，重复 ID 会被忽略。创建对话最多接受 1 MiB JSON（包括转义字符）；超过限制会在数据库或方案权限处理之前返回 `413`。响应为私有数据，不缓存。

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**请求体:**

```json
{
  "name": "My Conversation",
  "mindId": "your-mind-id"
}
```

<table>
<thead>
  <tr>
    <th>
      参数
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Chat 的显示名称(默认:"API Chat")
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mindId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      三者之一
    </td>
    
    <td>
      单个 Mind 的 UUID。必须提供 <code>
        mindId
      </code>
      
      、非空 <code>
        mindIds
      </code>
      
       数组或非空 <code>
        audienceIds
      </code>
      
       数组；全部省略将返回 <code>
        400
      </code>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mindIds
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      三者之一
    </td>
    
    <td>
      多个 Mind 的 UUID。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audienceIds
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      三者之一
    </td>
    
    <td>
      Study 对话使用的 Audience UUID。响应包含 <code>
        type: "study"
      </code>
      
       和 <code>
        audiences
      </code>
      
      ，而不是 <code>
        minds
      </code>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        responseThread
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      否
    </td>
    
    <td>
      可选 <code>
        { studyId, messageId }
      </code>
      
      ，用于与一个 Mind 继续讨论某个 Study 回答。保留已授权的来源上下文和文件。新建讨论返回 <code>
        201
      </code>
      
      ，恢复已有讨论返回 <code>
        200
      </code>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      可选描述
    </td>
  </tr>
</tbody>
</table>

**响应 (201):**

```json
{
  "data": {
    "id": "601af953-3837-49c1-a31e-4fdbfa82ac04",
    "name": "My Conversation",
    "description": null,
    "createdAt": "2026-04-04T12:45:24.078Z",
    "minds": [
      {
        "id": "4774888e-0a03-40d7-979b-39b47c4c049c",
        "name": "Ada Lovelace",
        "discipline": "mathematician and computer scientist"
      }
    ]
  }
}
```

### 发送消息

向已有 chat 发送消息。服务端会自动处理对话历史、上下文窗口压缩和滚动摘要。

**Endpoint:** `POST /api/v1/chats/{chatId}/messages`

单个和多个 Mind 的对话都会遵守各 Mind 已保存的 `knowledge_only` 策略及工作区的网页研究限制。受限 Mind 使用当前问题、已训练的人物设定和检索到的相关 Mind 知识；内部工具、客户端工具、先前对话上下文及复制的 Study 资料都不会进入其回答上下文。检索到相关证据时，回答中的 `metadata.knowledgeRetrieval.status` 为 `grounded`；没有可用证据或检索失败时为 `fallback`。多个 Mind 的回答会在各 `messages[]` 项目的 `metadata` 中分别报告该状态。

工作区的网页研究权限与 `knowledge_only` 相互独立：关闭该权限会移除网页搜索和链接分析工具，但使用 `auto` 的 Mind 仍保留用户提供的资料和对话历史。上述回答上下文限制适用于使用 `knowledge_only` 的 Mind。

滚动记忆从最后一条已涵盖消息的 ID 之后继续，而不依赖可能随复制的 Study 上下文变化而移动的位置。生成的摘要行不计入对话轮次；所有者编写的系统备注仍可用于 v1 对话。如果其他请求已修改后台任务所依据的已存摘要，该任务的结果将被丢弃。

如果滚动摘要失败或未返回叙述正文，回退处理会保留此前的摘要和有效的已存事实，并附上新对话片段的简短摘录。 回退处理每次最多摘录30条新纳入的消息，并且只将这些消息标记为已涵盖。其余消息仍可在后续更新中处理。请求压缩依据已存消息 ID，避免重复已涵盖的摘录，同时保留最近的消息、优先保留的证据以及复制的 Study 上下文。

主持器通过 Mind ID 识别参与者。显示名称相同的 Mind 仍是不同的候选者，发言次数限制和连续发言检查均按 ID 执行。主持器可能在所有 Mind 回答之前结束讨论。

意外生成失败会返回不含提供商内部详情的通用 `500`，并为失败回答申请退还预留额度。此前已生成的回答和已保存的消息不会回滚。明确的模型能力拒绝仍返回 `400`，附带 `data.errorType: "unsupported_model_capability"`。对于多 Mind 对话，可选的后台摘要不会延迟已保存的回答，也不会使其变成错误响应。

消息请求也受 1 MiB JSON 限制；超限会在数据库或方案权限处理前返回 `413`。响应为私有数据，不缓存。只有对话所有者可以发消息。托管工作区会在每次请求时重新验证当前工作区和所关联 Mind/Audience 的授权；权限被撤销时，会在保存或计费前返回 `404`。

下方响应示例针对单个 Mind。多 Mind 对话返回 `messages[]`，Study 对话返回 `outputData`。设置 `role: "system"` 可保存上下文备注，不触发生成或消耗消息额度；响应为 `{ messageId, role: "system" }`。

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

**请求体:**

```json
{
  "content": "What are the latest advancements in solar panel technology?"
}
```

<table>
<thead>
  <tr>
    <th>
      参数
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      消息文本(或使用 <code>
        message
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      覆盖此消息使用的 AI 模型。必须与 <code>
        provider
      </code>
      
       一起发送。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      模型覆盖使用的 AI 提供方:<code>
        openai
      </code>
      
      、<code>
        anthropic
      </code>
      
       或 <code>
        google
      </code>
      
      。必须与 <code>
        model
      </code>
      
       一起发送。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      否
    </td>
    
    <td>
      本次请求中真实终端用户的可选显示名称。如果省略、为 <code>
        null
      </code>
      
       或为空，Minds 会以中性方式称呼用户，不会从 API key 或账户所有者推断姓名。别名: <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      。
    </td>
  </tr>
</tbody>
</table>

有状态聊天的模型选择顺序为:每次请求的覆盖、团队首选提供方(如果已配置且有资格使用)、产品默认值。在此 endpoint 上,部分覆盖会以 `400 Bad Request` 拒绝;请同时发送 `model` 和 `provider`,或两者都不发送。

**响应:**

```json
{
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency...",
  "messageId": "cmnkbsddh00033v01ptk9t4et"
}
```

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind 的回复
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      保存的消息的唯一 ID
    </td>
  </tr>
</tbody>
</table>

### 多轮示例

使用有状态 chat 时,每次只发送新消息即可。服务端会记住所有内容:

```bash
# Step 1: Create a chat
CHAT=$(curl -s -X POST "https://getminds.ai/api/v1/chats" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Research Session", "mindId": "your-mind-id" }')

CHAT_ID=$(echo $CHAT | jq -r '.data.id')

# Step 2: Send messages (server manages history automatically)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "What are the top marketing trends?" }'

# Step 3: Follow up (the mind remembers the previous exchange)
curl -X POST "https://getminds.ai/api/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Which of those would work best on a small budget?" }'
```

**工作原理:**

- 每条消息都会持久化到数据库
- 对于历史较长的单个 Mind 对话，最近8条消息保留完整内容
- 较早的轮次使用可用的已存摘要，并补充尚未涵盖的消息摘录
- 摘要会丢失细节；很长的历史记录或较大的消息仍可能达到模型的上下文限制。

### 删除对话

`DELETE /api/v1/chats/{chatId}`

只有所有者可以永久删除对话及其消息。Minds 和 Audiences 会保留。成功时返回 `204`，无响应体，请勿将其解析为 JSON。凭证缺失或无效返回 `401`，他人拥有的对话返回 `403`，不存在的对话返回 `404`（包括在最终写入前被删除或转移的对话）。删除响应使用 `Cache-Control: private, no-store`。

---

## 无状态 Completion

用于单次请求,或当你想自行管理对话历史时。

### 发送消息

向 mind 发送消息并接收回复。

**Endpoint:** `POST /api/v1/minds/{mindId}/completion`

**Headers:**

```text
Authorization: Bearer minds_your_api_key
Content-Type: application/json
```

### 请求体

```json
{
  "messages": [
    {
      "role": "user",
      "content": "What are the latest advancements in solar panel technology?"
    }
  ]
}
```

### 参数

<table>
<thead>
  <tr>
    <th>
      参数
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messages
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      否
    </td>
    
    <td>
      消息对象数组(<code>
        system
      </code>
      
      , <code>
        user
      </code>
      
      、<code>
        assistant
      </code>
      
       或 <code>
        tool
      </code>
      
      )。省略或传空数组时,将返回与 mind 人格相符的问候语。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      <code>
        system
      </code>
      
      , <code>
        user
      </code>
      
      , <code>
        assistant
      </code>
      
      , <code>
        tool
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages[].content
      </code>
    </td>
    
    <td>
      string|array
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      字符串或结构化内容部分的数组。所有角色都必须提供。用户字符串必须包含非空白文本。发送工具结果时，保留 <code>
        content
      </code>
      
      ，并提供与先前助手调用匹配的 <code>
        tool_call_id
      </code>
      
      。 <code>
        system
      </code>
      
       角色仅接受字符串内容。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      覆盖本次请求使用的 AI 模型。参见下方 <a href="#model-override">
        model override
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      model override 所用的 AI provider:<code>
        openai
      </code>
      
      、<code>
        anthropic
      </code>
      
       或 <code>
        google
      </code>
      
      。通常可从模型名自动识别。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        modelConnection
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      否
    </td>
    
    <td>
      已验证的团队模型连接的 <code>
        { "id", "revision" }
      </code>
      
      ：由你自己的端点生成回答。不能与 <code>
        model
      </code>
      
      /<code>
        provider
      </code>
      
       同时使用。参见<a href="#your-own-model">
        你自己的模型
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endUserName
      </code>
    </td>
    
    <td>
      string|null
    </td>
    
    <td>
      否
    </td>
    
    <td>
      本次请求中真实终端用户的可选显示名称。如果省略、为 <code>
        null
      </code>
      
       或为空，Minds 会以中性方式称呼用户，不会从 API key 或账户所有者推断姓名。别名: <code>
        userDisplayName
      </code>
      
      , <code>
        userName
      </code>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        language
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      回复语言提示。支持:<code>
        en
      </code>
      
      、<code>
        de
      </code>
      
      、<code>
        es
      </code>
      
      、<code>
        fr
      </code>
      
      、<code>
        zh
      </code>
      
      、<code>
        tr
      </code>
      
      、<code>
        ar
      </code>
      
      、<code>
        ja
      </code>
      
      、<code>
        ko
      </code>
      
      。强人格(如固定母语的公众人物克隆)可能仍以其人格语言回复。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generateImage
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      否
    </td>
    
    <td>
      设为 <code>
        true
      </code>
      
       时,若上下文合适将在回复中启用 AI 图像生成
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        response_format
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      否
    </td>
    
    <td>
      请求结构化输出。参见下方 <a href="#structured-output">
        structured output
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tools
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      否
    </td>
    
    <td>
      用户自定义 tool 定义数组。参见下方 <a href="#tool-calling">
        tool calling
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_choice
      </code>
    </td>
    
    <td>
      string|object
    </td>
    
    <td>
      否
    </td>
    
    <td>
      控制 tool 调用行为。参见 <a href="#tool-choice-modes">
        tool choice modes
      </a>
      
      。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parallel_tool_calls
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      否
    </td>
    
    <td>
      允许单轮多次 tool 调用(默认:<code>
        true
      </code>
      
      )。
    </td>
  </tr>
</tbody>
</table>

### 响应

```json
{
  "messageId": "msg_550e840029b141d4a716446655440000",
  "content": "Recent advancements in solar panel technology include perovskite cells with 30%+ efficiency, bifacial panels that capture light from both sides, and integrated storage systems...",
  "metadata": {
    "ragCitations": [
      {
        "id": "abc123",
        "displaySource": "Mind knowledge",
        "similarity": 0.89
      }
    ]
  }
}
```

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        messageId
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      用于追踪的唯一消息标识
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Mind 的回复文本(使用结构化输出时为 JSON 字符串)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parsed
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      已解析的 JSON 对象(仅在使用 <code>
        response_format
      </code>
      
       时存在)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_calls
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      Tool 调用请求数组(仅在触发用户自定义 tool 时存在)。每项含:<code>
        id
      </code>
      
      、<code>
        name
      </code>
      
      、<code>
        arguments
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      可选元数据(citations、images)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata.ragCitations
      </code>
    </td>
    
    <td>
      array
    </td>
    
    <td>
      回复中使用的知识来源与网络搜索结果
    </td>
  </tr>
</tbody>
</table>

## 单条消息示例

提出一个问题:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top 3 marketing trends for 2025?"
      }
    ]
  }'
```

## 多轮对话

通过带上之前的消息来保留对话上下文:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are the top marketing trends?"
      },
      {
        "role": "assistant",
        "content": "The top trends are AI personalization, short-form video, and community building..."
      },
      {
        "role": "user",
        "content": "How can I implement AI personalization on a budget?"
      }
    ]
  }'
```

**多轮对话建议:**

- 每次请求都带上完整对话历史
- 顺序很重要:消息应按时间先后排列
- `user` 与 `assistant` role 交替出现
- 最后一条消息应始终来自 `user`

## 文件附件

附加文件、文档、图片和链接,为 mind 提供上下文。Mind 会将处理后的内容作为对话的一部分接收。

### 附加文件

通过 user 消息中的 `metadata.attachedFiles` 数组添加文件:

无状态补全请求应使用自己上传的文件、带有效签名的聊天文件 URL，或通过上传者的 Study 共享的上下文。无权访问的工作区文件会返回 `403 Upload access denied`（流式模式下为错误帧）。外部 HTTP(S) URL 保留自身的访问令牌，不会根据任意存储路径重新签名。请将示例中的 `your-user-id` 替换为自己的用户 ID，并使用上传端点返回的路径。

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Please review this document and summarize the key points",
        "metadata": {
          "attachedFiles": [
            {
              "url": "https://example.com/quarterly-report.pdf",
              "name": "Q4 2025 Report",
              "type": "application/pdf"
            },
            {
              "path": "chat/your-user-id/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'
```

### 附件格式

每个附件对象支持:

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否*
    </td>
    
    <td>
      文件的外部 URL(HTTP/HTTPS)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否*
    </td>
    
    <td>
      Supabase 存储路径(自动签名)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      文件的显示名称
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      MIME 类型(如 <code>
        application/pdf
      </code>
      
      、<code>
        image/png
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      可选描述
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcription
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      预转录的音视频内容
    </td>
  </tr>
</tbody>
</table>

**注意:** `url` 与 `path` 二选一,不要同时提供。

### 支持的文件类型

**文档:**

- PDF (`.pdf`) - 文本抽取 + 扫描页的 OCR
- Word (`.docx`) - 全文抽取
- Text (`.txt`、`.md`) - 直接文本内容
- CSV/Excel (`.csv`、`.xlsx`) - 表格抽取

**图片:**

- PNG、JPG、WEBP - OCR + 视觉分析
- 支持图像理解的 vision 能力

**外部 URL:**

- 使用 Firecrawl 抓取网页(JS 渲染 + 截图)
- 自动转换为 markdown

### 处理流程

文件在送达 mind 前会自动处理:

1. **下载** - 从 URL 或 Supabase 存储获取文件
2. **抽取** - 抽取内容(PDF 中的文本、图片 OCR 等)
3. **注入** - 将处理后的内容加入对话上下文
4. **回复** - Mind 同时看到你的消息和文件内容

**处理限制:**

- 超时:每个文件 30 秒
- 文件并行处理
- 处理失败的文件以友好的兜底消息呈现

### 多文件示例

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Compare these two proposals and recommend which one to pursue",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/proposal-a.pdf",
            "name": "Proposal A - Cloud Migration",
            "type": "application/pdf"
          },
          {
            "url": "https://example.com/proposal-b.pdf",
            "name": "Proposal B - On-Prem Upgrade",
            "type": "application/pdf"
          },
          {
            "path": "chat/your-user-id/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}
```

### 对话历史中的文件附件

在有附件的对话中继续交互时,历史中应包含带附件的原始消息:

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://example.com/sales-q4.csv",
            "name": "Q4 Sales Data"
          }
        ]
      }
    },
    {
      "role": "assistant",
      "content": "Based on the Q4 sales data, I can see that revenue increased by 23% compared to Q3..."
    },
    {
      "role": "user",
      "content": "What were the top 3 performing products?"
    }
  ]
}
```

**注意:** 文件只在首次附加时处理一次。同一对话中的后续消息会引用已处理好的内容。

### 网页链接

对网页和外部内容,使用 `url` 字段:

```json
{
  "messages": [
    {
      "role": "user",
      "content": "Summarize the key findings from this research paper",
      "metadata": {
        "attachedFiles": [
          {
            "url": "https://arxiv.org/pdf/2103.12345.pdf",
            "name": "AI Research Paper",
            "type": "application/pdf"
          }
        ]
      }
    }
  ]
}
```

**针对网页的特别说明:**

- 重度依赖 JavaScript 的站点使用 Firecrawl 渲染
- 捕获截图以提供视觉上下文
- 内容转换为清洁的 markdown

### 错误处理

若文件处理失败:

- Mind 将收到一条兜底消息,提示文件已附加但处理失败
- 对话正常继续
- 超时错误显示 `[Processing timeout - file may be too large]`
- 其他错误显示 `[Processing failed - file uploaded but analysis unavailable]`

这确保即便处理失败,mind 仍能感知到你尝试附加的文件。

## 初始消息(问候)

若传入空的 messages 数组或不传 messages,mind 将自我介绍:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": []
  }'
```

响应:

```json
{
  "content": "Hi! I'm Sarah, a marketing director with 15 years of experience in B2B SaaS. I specialize in growth marketing and data-driven strategies. What can I help you with today?"
}
```

## Model Override

你可以通过传入 `model` 参数,选择性覆盖无状态 completion 请求使用的 AI 模型。这适用于基准测试、成本优化或测试不同模型的行为。有状态聊天和 panel endpoint 会进行更严格的覆盖校验:请同时发送 `model` 和 `provider`。

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What are your thoughts on sustainable packaging?"
      }
    ],
    "model": "gpt-6-luna"
  }'
```

未指定 `model` 时使用服务端默认模型。

### Provider

<table>
<thead>
  <tr>
    <th>
      Provider
    </th>
    
    <th>
      值
    </th>
    
    <th>
      示例模型
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      OpenAI
    </td>
    
    <td>
      <code>
        openai
      </code>
    </td>
    
    <td>
      <code>
        gpt-6-astra
      </code>
      
      、<code>
        gpt-6.1-sol
      </code>
      
      、<code>
        gpt-6-luna
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Anthropic
    </td>
    
    <td>
      <code>
        anthropic
      </code>
    </td>
    
    <td>
      <code>
        claude-fable-5-1
      </code>
      
      、<code>
        claude-opus-5-5
      </code>
      
      、<code>
        claude-sonnet-5-5
      </code>
      
      、<code>
        claude-haiku-4-5-20251001
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Google
    </td>
    
    <td>
      <code>
        google
      </code>
    </td>
    
    <td>
      <code>
        gemini-3.8-flash
      </code>
      
      、<code>
        gemini-3.5-flash-lite
      </code>
    </td>
  </tr>
</tbody>
</table>

请传入上表列出的模型之一。已停用的 ID 会被转发(见下文),其他任何模型都会返回 `400 Bad Request`。provider 会基于常见模型名前缀自动识别(`claude-` → Anthropic、`gemini-` → Google、`gpt-`/`o1`/`o3`/`o4` → OpenAI)。

### Your own model

如需运行微调模型或自托管模型，由团队管理员将其添加为[团队模型连接](/guide/team-model-connections)（OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 协议）并完成验证。然后发送该连接的 ID 和当前修订版本，而不是 `model` 和 `provider`：

```json
{
  "messages": [...],
  "modelConnection": { "id": "3f6c1e2a-5b7d-4c1e-9a0f-2d8e4b6a1c90", "revision": 3 }
}
```

`GET /api/v1/model-connections` 会列出你团队的连接及其修订版本和已验证的能力。连接需要支持文本和流式输出；发送 `response_format` 时还需要结构化输出，请求使用工具时还需要工具调用。如果你的端点失败，请求也会失败：Minds 绝不会切换到自己的模型。图片和其他媒体会以 `MODEL_CONNECTION_MEDIA_UNVERIFIED` 被拒绝。有状态聊天消息（`/chats/{chatId}/messages`）不接受连接。

## Structured Output

使用 `response_format` 参数请求保证符合特定 schema 的 JSON 响应。它遵循 OpenAI 风格的结构化输出模式,适用于从对话中抽取结构化数据。

### JSON Schema 模式

强制模型输出符合你 schema 的有效 JSON:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Analyze the sentiment of this text: I love this product, it exceeded all my expectations!"
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "sentiment_analysis",
        "description": "Sentiment analysis result",
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "string",
              "enum": ["positive", "negative", "neutral"]
            },
            "confidence": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "keywords": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["sentiment", "confidence", "keywords"]
        }
      }
    }
  }'
```

响应:

```json
{
  "content": "{\"sentiment\": \"positive\", \"confidence\": 0.95, \"keywords\": [\"love\", \"exceeded\", \"expectations\"]}",
  "parsed": {
    "sentiment": "positive",
    "confidence": 0.95,
    "keywords": ["love", "exceeded", "expectations"]
  }
}
```

### JSON Object 模式

强制 JSON 输出但不做 schema 校验:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "List 3 marketing ideas as JSON"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'
```

### Response Format 类型

<table>
<thead>
  <tr>
    <th>
      类型
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
    </td>
    
    <td>
      默认文本输出(当前行为)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_object
      </code>
    </td>
    
    <td>
      强制有效 JSON 输出,不做 schema 校验
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json_schema
      </code>
    </td>
    
    <td>
      强制输出符合指定 schema 的 JSON
    </td>
  </tr>
</tbody>
</table>

### JSON Schema 字段

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      Schema 标识符
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      否
    </td>
    
    <td>
      Schema 含义的描述
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        schema
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      JSON Schema 定义
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      否
    </td>
    
    <td>
      强制严格遵循 schema(默认:<code>
        true
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

### 支持的 Schema 特性

支持以下 JSON Schema 特性:

- **类型**:`string`、`number`、`integer`、`boolean`、`array`、`object`、`null`
- **约束**:`enum`、`minimum`、`maximum`、`minLength`、`maxLength`、`minItems`、`maxItems`
- **结构**:`properties`、`required`、`items`、`additionalProperties`
- **元数据**:`description`(用于引导模型)

### 说明

- Tool(RAG、网络搜索等)与结构化输出可共同工作 —— mind 在生成结构化响应前仍可检索自己的知识库
- `parsed` 字段为方便使用直接给出解析后的 JSON 对象;`content` 则为原始 JSON 字符串
- 所有主要 provider(OpenAI、Anthropic、Google)都支持结构化输出
- 对于复杂 schema,建议添加 `description` 字段来引导模型输出

## Tool Calling

让 mind 在对话中调用你自定义的函数。它遵循 OpenAI 兼容的 function calling 模式,可通过外部 tool 和 API 扩展 mind 的能力。

### 工作方式

1. **定义 tool**:传入带名称、描述和 JSON Schema 参数的 tool 定义
2. **Mind 决策**:mind 根据对话决定何时调用你的 tool(或你通过 `tool_choice` 强制调用)
3. **API 返回 tool 调用**:响应中包含带 tool 名称和生成参数的 `tool_calls`
4. **执行 tool**:在你的应用中运行 tool 并拿到结果
5. **回传结果**:在下一条消息中以 `role: "tool"` 带上结果
6. **Mind 回复**:mind 将 tool 结果整合进最终回复

### 基础示例

**带 tool 的请求:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            },
            "units": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "Temperature units"
            }
          },
          "required": ["city"]
        }
      }
    ]
  }'
```

**响应:**

```json
{
  "content": "",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "get_weather",
      "arguments": {
        "city": "Berlin",
        "units": "celsius"
      }
    }
  ]
}
```

**执行 tool 并回传结果:**

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in Berlin?"
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "name": "get_weather",
            "arguments": {
              "city": "Berlin",
              "units": "celsius"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": "{\"temperature\": 18, \"condition\": \"partly cloudy\", \"humidity\": 65}"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" },
            "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["city"]
        }
      }
    ]
  }'
```

**最终响应:**

```json
{
  "content": "The current weather in Berlin is 18°C and partly cloudy, with 65% humidity."
}
```

### Tool 定义 Schema

每个 tool 必须遵循如下结构:

```json
{
  "name": "tool_name",
  "description": "Clear description of when and how to use this tool",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter does"
      }
    },
    "required": ["param1"]
  },
  "strict": true
}
```

**必填字段:**

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      函数名。必须唯一,且不能与内置 tool 冲突。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      清晰描述该 tool 的作用与使用时机。它直接影响 mind 的 tool 选择。
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parameters
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      定义函数参数的 JSON Schema。
    </td>
  </tr>
</tbody>
</table>

**可选字段:**

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      默认值
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        strict
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      对参数强制严格的 schema 校验。
    </td>
  </tr>
</tbody>
</table>

### Tool Choice 模式

通过 `tool_choice` 参数控制 mind 何时、如何调用 tool:

<table>
<thead>
  <tr>
    <th>
      值
    </th>
    
    <th>
      行为
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        "auto"
      </code>
    </td>
    
    <td>
      由 mind 决定是否调用 tool(默认)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "required"
      </code>
    </td>
    
    <td>
      Mind 必须在回复前至少调用一个 tool
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        "none"
      </code>
    </td>
    
    <td>
      本轮禁用 tool 调用
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {"name": "tool_name"}
      </code>
    </td>
    
    <td>
      强制 mind 调用指定 tool
    </td>
  </tr>
</tbody>
</table>

**示例:**

```json
// Let the mind decide
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "auto"
}

// Force a specific tool
{
  "messages": [...],
  "tools": [...],
  "tool_choice": {
    "name": "search_database"
  }
}

// Require at least one tool call
{
  "messages": [...],
  "tools": [...],
  "tool_choice": "required"
}
```

### 并行 Tool 调用

默认情况下,mind 可在单轮中调用多个 tool 以提升效率:

```json
{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "get_customer",
      "arguments": { "id": "CUST-001" }
    },
    {
      "id": "call_2",
      "name": "get_customer",
      "arguments": { "id": "CUST-002" }
    }
  ]
}
```

要禁用并行调用、强制顺序执行:

```json
{
  "messages": [...],
  "tools": [...],
  "parallel_tool_calls": false
}
```

### Tool 消息格式

回传 tool 结果时,使用 `tool` role:

```json
{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"result\": \"success\", \"data\": {...}}"
}
```

<table>
<thead>
  <tr>
    <th>
      字段
    </th>
    
    <th>
      类型
    </th>
    
    <th>
      必填
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        role
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      必须为 <code>
        "tool"
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tool_call_id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      来自 assistant 响应中 tool call 的 <code>
        id
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <strong>
        是
      </strong>
    </td>
    
    <td>
      Tool 执行结果(通常为 JSON 字符串)
    </td>
  </tr>
</tbody>
</table>

工具结果应放在对应的助手消息之后，并保留该消息的 `tool_calls`。使用返回的调用 ID 和名称，每个结果只提交一次。格式错误的参数、未知调用 ID、不匹配的工具名称、重复结果以及缺失的客户端结果都会在生成前返回 `400`。

### 内置 Tool 与用户 Tool

Minds 提供自动执行的服务端内置 tool:

<table>
<thead>
  <tr>
    <th>
      内置 Tool
    </th>
    
    <th>
      用途
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET_SPARK_RAG
      </code>
    </td>
    
    <td>
      检索 mind 的知识库
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        WEB_SEARCH
      </code>
    </td>
    
    <td>
      网络搜索
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GENERATE_IMAGE
      </code>
    </td>
    
    <td>
      使用 AI 生成图片
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DISPLAY_IMAGE
      </code>
    </td>
    
    <td>
      显示 mind 记忆中的图片
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DOCUMENT_PROCESSING
      </code>
    </td>
    
    <td>
      分析已上传文件
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ANALYZE_LINK
      </code>
    </td>
    
    <td>
      抓取并分析网页 URL
    </td>
  </tr>
</tbody>
</table>

**关键区别:**

- **内置 tool**:服务端执行,结果包含在 `content` 和 `metadata` 中,绝不在 `tool_calls` 中返回。
- **用户 tool**:在 `tool_calls` 中返回供你执行。结果需以 `tool` 消息回传。

你无法覆盖或禁用内置 tool。用户 tool 是**叠加的** —— 用于扩展 mind 的能力。

### 完整多 Tool 示例

一个带多个自定义 tool 的法律助理 mind:

```bash
curl -X POST "https://getminds.ai/api/v1/minds/mind-id/completion" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Create a new case for Schmidt vs. Mueller and search for similar precedents"
      }
    ],
    "tools": [
      {
        "name": "create_case",
        "description": "Create a new legal case in the system",
        "parameters": {
          "type": "object",
          "properties": {
            "title": {
              "type": "string",
              "description": "Case title (parties involved)"
            },
            "practice_area": {
              "type": "string",
              "enum": ["corporate", "litigation", "employment", "ip"],
              "description": "Legal practice area"
            },
            "client_id": {
              "type": "string",
              "description": "Client identifier"
            }
          },
          "required": ["title", "practice_area"]
        }
      },
      {
        "name": "search_precedents",
        "description": "Search legal database for similar cases",
        "parameters": {
          "type": "object",
          "properties": {
            "keywords": {
              "type": "array",
              "items": { "type": "string" },
              "description": "Search keywords"
            },
            "practice_area": {
              "type": "string",
              "description": "Filter by practice area"
            },
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "description": "Maximum number of results"
            }
          },
          "required": ["keywords"]
        }
      }
    ],
    "parallel_tool_calls": true
  }'
```

**带并行 tool 调用的响应:**

```json
{
  "content": "",
  "tool_calls": [
    {
      "id": "call_1",
      "name": "create_case",
      "arguments": {
        "title": "Schmidt vs. Mueller",
        "practice_area": "litigation"
      }
    },
    {
      "id": "call_2",
      "name": "search_precedents",
      "arguments": {
        "keywords": ["Schmidt", "Mueller"],
        "practice_area": "litigation",
        "max_results": 10
      }
    }
  ]
}
```

### 最佳实践

1. **写清晰的描述**:`description` 字段至关重要。明确说明每个 tool 的使用时机与原因。```json
❌ "description": "Search database"
✅ "description": "Search the legal precedents database for similar cases based on keywords and practice area"
```
2. **为参数添加描述**:帮助 mind 理解每个参数的作用。```json
"case_id": {
  "type": "string",
  "description": "Unique case identifier in format CASE-YYYY-NNNN"
}
```
3. **对受限取值使用 enum**:```json
"status": {
  "type": "string",
  "enum": ["pending", "active", "closed", "archived"]
}
```
4. **设置校验约束**:```json
"priority": {
  "type": "integer",
  "minimum": 1,
  "maximum": 5,
  "description": "Priority level (1=lowest, 5=highest)"
}
```
5. **启用 strict 模式**:保持 `strict: true`(默认),确保 mind 生成合法参数。
6. **返回结构化的 tool 结果**:用 JSON 让结果易于解析:```json
{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "{\"success\": true, \"case_id\": \"CASE-2026-001\", \"created_at\": \"2026-03-30T23:00:00Z\"}"
}
```
7. **优雅处理错误**:在 tool 结果中返回错误详情:```json
{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "{\"success\": false, \"error\": \"Case already exists\", \"error_code\": \"DUPLICATE_CASE\"}"
}
```

### 限制

- 每次请求**最多 128 个 tool**
- Tool 名称必须唯一,且不能与内置 tool 名冲突
- Tool 执行发生在客户端 —— 你需自行运行并保障 tool 的安全
- Tool 结果必须回传到对话历史,mind 才能据此回复

### JSON Schema 支持

`parameters` 字段支持标准的 JSON Schema 特性:

**类型:**

- `string`、`number`、`integer`、`boolean`、`array`、`object`、`null`

**校验:**

- `enum` —— 限制为特定取值
- `minimum`、`maximum` —— 数值范围
- `minLength`、`maxLength` —— 字符串长度
- `minItems`、`maxItems` —— 数组大小
- `pattern` —— 正则校验
- `format` —— 字符串格式(如 `"date-time"`、`"email"`、`"uri"`)

**结构:**

- `properties` —— 对象属性
- `required` —— 必填字段
- `items` —— 数组元素 schema
- `additionalProperties` —— 是否允许额外属性

**高级校验示例:**

```json
{
  "name": "schedule_meeting",
  "description": "Schedule a meeting with a client",
  "parameters": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Meeting date and time in ISO 8601 format"
      },
      "attendees": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1,
        "maxItems": 20
      },
      "duration_minutes": {
        "type": "integer",
        "minimum": 15,
        "maximum": 480,
        "description": "Meeting duration (15-480 minutes)"
      }
    },
    "required": ["title", "date", "attendees"]
  }
}
```

## 工作原理

### 1. 上下文加载

当你发送消息时,mind 会:

- 加载其 system prompt 和配置
- **自动检索其知识库**以获取相关信息
- 综合考虑对话历史

### 2. 处理

Mind 会:

- 在上下文中分析你的消息
- **基于检索到的知识生成回答**并附上 citation
- 按需调用额外 tool(网络搜索、图像生成等)
- 生成符合其人格的回复

### 3. 响应生成

Mind 会:

- 生成体现其专长的回复
- **附上 citation**,当使用知识库或网络来源时
- 返回消息,并可选带上元数据(citations、images 等)

## 元数据

响应可包含额外元数据:

### 图片

当 mind 生成或展示图片时:

```json
{
  "content": "Here are some logo concepts...",
  "metadata": {
    "images": [
      {
        "id": "img_123",
        "url": "https://...",
        "filename": "Logo Concept 1",
        "description": "Modern minimalist logo with blue gradient",
        "source": "generated"
      }
    ]
  }
}
```

### 知识 Citation

当 mind 从知识库或网络搜索中检索到信息时:

```json
{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Mind knowledge",
        "similarity": 0.85
      },
      {
        "id": "external-web-123",
        "displaySource": "https://example.com/solar-research",
        "similarity": 0.92
      }
    ]
  }
}
```

**Citation 字段:**

- `id` - 来源的唯一标识
- `displaySource` - 人类可读的来源名称或 URL
- `similarity` - 相关性分数(0-1),反映该来源与问题的契合度

Mind 会在回复前自动检索知识库,并在其答案基于特定来源时附上 citation。

## 访问控制

你可以与以下 mind 对话:

- **拥有** - 你创建的 mind
- **被授权** - 团队成员分享给你的 mind
- **所在成员** - 你所属团队 workspace 中的 mind
- **公共 mind** - 公开可访问的 mind

尝试访问无权限的 mind 会返回:

```json
{
  "statusCode": 403,
  "statusMessage": "Access denied"
}
```

## 响应格式

### 文本响应

大多数响应是纯文本:

```json
{
  "content": "Based on current trends, I recommend focusing on..."
}
```

### 结构化响应

部分 mind 可能返回结构化内容:

```json
{
  "content": "Here's my analysis:\n\n1. Trend: AI Personalization\n   - Impact: High\n   - Timeline: 6-12 months\n\n2. Trend: Short-form Video\n   - Impact: Very High\n   - Timeline: Immediate"
}
```

### 空内容带元数据的响应

有时仅返回元数据(例如图像生成):

```json
{
  "content": "",
  "metadata": {
    "images": [...]
  }
}
```

## 最佳实践

### 要具体

```text
❌ "Tell me about marketing"
✅ "What are the most cost-effective digital marketing channels for a B2B SaaS startup with a $5K monthly budget?"
```

### 提供上下文

```text
✅ "We're launching a sustainable fashion brand targeting Gen Z. What social media strategy would you recommend?"
```

### 善用追问

充分利用对话记忆:

```text
User: "What are the top trends?"
Assistant: "The top trends are..."
User: "Which of these would work best for a small budget?"
Assistant: "For a small budget, I'd focus on..."
```

### 引用知识

如果你上传了知识,主动引用:

```text
✅ "Based on our brand guidelines, what tone should we use for this campaign?"
```

## 错误响应

### 400 Bad Request

缺少或无效的 Mind ID:

```json
{
  "statusCode": 400,
  "statusMessage": "Mind ID is required"
}
```

不支持的 provider:

```json
{
  "statusCode": 400,
  "statusMessage": "Unsupported provider: 'invalid'. Supported providers: openai, anthropic, google."
}
```

名称不明确且未指定 provider:

```json
{
  "statusCode": 400,
  "statusMessage": "Cannot auto-detect provider for model 'my-model'. Please specify a 'provider' parameter (openai, anthropic, or google)."
}
```

### 401 Unauthorized

API key 无效。

### 403 Forbidden

无权访问 Mind:

```json
{
  "statusCode": 403,
  "statusMessage": "Access denied"
}
```

### 404 Not Found

Mind 不存在:

```json
{
  "statusCode": 404,
  "statusMessage": "Mind not found"
}
```

## 使用说明

- v1 API 按已认证账户执行可配置限流（默认每分钟 300 个请求）
- 请读取 `RateLimit-Limit` 和 `RateLimit-Remaining`，在 `429` 后遵循 `Retry-After`
- 生成请求会消耗大量资源，请限制并行 completion 数量

## 下一步

- 了解 [latency 与性能](/docs/api/latency)
- 了解 [错误与 rate limit](/docs/api/errors)
- 创建你的第一个 [mind](/docs/api/minds)
- 上传 [knowledge](/docs/api/knowledge) 以增强回复
- 阅读 [API 概览](/docs/api/overview)