Chat API

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

有状态 Chat(推荐)

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

创建 Chat

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

Endpoint: POST /api/v1/chats

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体:

{
  "name": "My Conversation",
  "sparkId": "your-spark-id"
}

响应 (201):

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

发送消息

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

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

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体:

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

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

响应:

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

多轮示例

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

# 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", "sparkId": "your-spark-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?" }'

工作原理:

• 每条消息都会持久化到数据库
• 最近 8 条消息以完整上下文发送
• 较早的消息会被压缩成滚动式 LLM 摘要
• 对话可持续数周/数月而不触及上下文限制

无状态 Completion

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

发送消息

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

Endpoint: POST /api/v1/sparks/{sparkId}/completion

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

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

参数

响应

{
  "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": "Spark knowledge",
        "similarity": 0.89
      }
    ]
  }
}

单条消息示例

提出一个问题:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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?"
      }
    ]
  }'

多轮对话

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

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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 数组添加文件:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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": "uploads/meeting-notes.docx",
              "name": "Strategy Meeting Notes"
            }
          ]
        }
      }
    ]
  }'

附件格式

每个附件对象支持:

注意: 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 秒
• 文件并行处理
• 处理失败的文件以友好的兜底消息呈现

多文件示例

{
  "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": "uploads/budget-analysis.xlsx",
            "name": "Budget Comparison"
          }
        ]
      }
    }
  ]
}

对话历史中的文件附件

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

{
  "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 字段:

{
  "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 将自我介绍:

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

响应:

{
  "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。

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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-4o-mini"
  }'

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

Provider

你可以传入 provider 支持的任意模型字符串。provider 会基于常见模型名前缀自动识别(claude- → Anthropic、gemini- → Google、gpt-/o1/o3/o4 → OpenAI)。

对于名称不明确的模型,请显式指定 provider:

{
  "messages": [...],
  "model": "my-custom-fine-tune",
  "provider": "openai"
}

若无法识别 provider,API 将返回 400 Bad Request 错误,要求你明确指定。

Structured Output

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

JSON Schema 模式

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

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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"]
        }
      }
    }
  }'

响应:

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

JSON Object 模式

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

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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 类型

JSON Schema 字段

支持的 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 决策 根据对话决定何时调用你的 tool(或你通过 tool_choice 强制调用)
3. API 返回 tool 调用:响应中包含带 tool 名称和生成参数的 tool_calls
4. 执行 tool:在你的应用中运行 tool 并拿到结果
5. 回传结果:在下一条消息中以 role: "tool" 带上结果
6. Mind 回复 将 tool 结果整合进最终回复

基础示例

带 tool 的请求:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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"]
        }
      }
    ]
  }'

响应:

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

执行 tool 并回传结果:

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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"]
        }
      }
    ]
  }'

最终响应:

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

Tool 定义 Schema

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

{
  "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
}

必填字段:

可选字段:

Tool Choice 模式

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

示例:

// 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 以提升效率:

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

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

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

Tool 消息格式

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

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

内置 Tool 与用户 Tool

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

关键区别:

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

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

完整多 Tool 示例

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

curl -X POST "https://getminds.ai/api/v1/sparks/spark-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 调用的响应:

{
  "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 的使用时机与原因。

   ❌ "description": "Search database"
   ✅ "description": "Search the legal precedents database for similar cases based on keywords and practice area"
   

2. 为参数添加描述:帮助 mind 理解每个参数的作用。

   "case_id": {
     "type": "string",
     "description": "Unique case identifier in format CASE-YYYY-NNNN"
   }
   

3. 对受限取值使用 enum:

   "status": {
     "type": "string",
     "enum": ["pending", "active", "closed", "archived"]
   }
   

4. 设置校验约束:

   "priority": {
     "type": "integer",
     "minimum": 1,
     "maximum": 5,
     "description": "Priority level (1=lowest, 5=highest)"
   }
   

5. 启用 strict 模式:保持 strict: true(默认),确保 mind 生成合法参数。
6. 返回结构化的 tool 结果:用 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 结果中返回错误详情:

   {
     "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 —— 是否允许额外属性

高级校验示例:

{
  "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 生成或展示图片时:

{
  "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 从知识库或网络搜索中检索到信息时:

{
  "content": "Based on recent research, solar panel efficiency has improved significantly...",
  "metadata": {
    "ragCitations": [
      {
        "id": "9bf44ab0-9d83-42ec-b941-c0ab7610e949",
        "displaySource": "Spark 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 会返回:

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

响应格式

文本响应

大多数响应是纯文本:

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

结构化响应

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

{
  "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"
}

空内容带元数据的响应

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

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

最佳实践

要具体

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

提供上下文

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

善用追问

充分利用对话记忆:

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

引用知识

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

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

错误响应

400 Bad Request

缺少或无效的 spark ID:

{
  "statusCode": 400,
  "statusMessage": "Spark ID is required"
}

不支持的 provider:

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

名称不明确且未指定 provider:

{
  "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

无权访问 spark:

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

404 Not Found

Spark 不存在:

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

使用说明

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

下一步

• 了解 latency 与性能
• 了解 错误与 rate limit
• 创建你的第一个 mind
• 上传 knowledge 以增强回复
• 阅读 API 概览