Panels API

Panels 让你向多组 AI minds 提问，并获取经过聚合处理的结构化响应。适用于市场调研模拟、基于人设的反馈收集，以及多视角分析。

Base URL： https://getminds.ai/api/v1 或 https://api.getminds.ai/v1

核心概念

获取 Panel 列表

获取当前认证用户的所有 panels。

接口： GET /api/v1/panels

请求头：

Authorization: Bearer minds_your_api_key

响应

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Consumer Research Panel",
      "flowMode": "panel",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T14:30:00.000Z",
      "messageCount": 8,
      "groups": [
        {
          "id": "group-123",
          "name": "Gen Z Consumers",
          "sparkCount": 5,
          "sparks": [
            {
              "id": "spark-1",
              "name": "Emma",
              "discipline": "College Student",
              "profileImageUrl": "https://..."
            }
          ]
        }
      ]
    }
  ]
}

响应字段说明

请求示例

curl -X GET "https://getminds.ai/api/v1/panels" \
  -H "Authorization: Bearer minds_your_api_key"

创建 Panel

创建一个新 panel，并可选择关联 mind 组。

接口： POST /api/v1/panels

请求头：

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

{
  "name": "Product Feedback Panel",
  "groupIds": ["group-123", "group-456"]
}

参数说明

响应

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Feedback Panel",
    "flowMode": "panel",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "groups": [
      {
        "id": "group-123",
        "name": "Early Adopters",
        "sparks": [
          {
            "id": "spark-1",
            "name": "Alex",
            "discipline": "Tech Enthusiast",
            "profileImageUrl": "https://..."
          }
        ]
      }
    ]
  }
}

请求示例

curl -X POST "https://getminds.ai/api/v1/panels" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Market Research Panel",
    "groupIds": ["group-123", "group-456"]
  }'

错误响应

400 Bad Request - 缺少 name 或 group ID 无效

{
  "statusCode": 400,
  "message": "name is required"
}

{
  "statusCode": 404,
  "message": "Groups not found: 1f2e3d4c-..."
}

获取 Panel 详情

获取指定 panel 的完整信息，包括所有组和消息历史。

接口： GET /api/v1/panels/{panelId}

请求头：

Authorization: Bearer minds_your_api_key

响应

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Consumer Research Panel",
    "flowMode": "panel",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T14:30:00.000Z",
    "groups": [
      {
        "id": "group-123",
        "name": "Gen Z Consumers",
        "sparks": [
          {
            "id": "spark-1",
            "name": "Emma",
            "discipline": "College Student",
            "profileImageUrl": "https://..."
          }
        ]
      }
    ],
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": "How important is sustainability when choosing products?",
        "metadata": {
          "groupIds": ["group-123"]
        },
        "createdAt": "2025-12-10T14:00:00.000Z"
      },
      {
        "id": "msg-2",
        "role": "assistant",
        "content": "How important is sustainability when choosing products?",
        "metadata": {
          "outputData": {
            "title": "How important is sustainability when choosing products?",
            "type": "scale",
            "groups": [
              {
                "group": "Gen Z Consumers",
                "value": "Very Important",
                "answers": [
                  {
                    "value": "9/10",
                    "persona": "Emma",
                    "discipline": "College Student",
                    "message": "Sustainability is a top priority for me..."
                  }
                ]
              }
            ]
          },
          "outputType": "bar"
        },
        "createdAt": "2025-12-10T14:00:30.000Z"
      }
    ]
  }
}

请求示例

curl -X GET "https://getminds.ai/api/v1/panels/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer minds_your_api_key"

错误响应

403 Forbidden - 无权访问该 panel

404 Not Found - Panel 不存在

向 Panel 提问

向 panel 中所有 minds 发送问题，以流式方式返回响应及聚合结果。

接口： POST /api/v1/panels/{panelId}/ask

请求头：

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

基础提问：

{
  "question": "What features would make you switch to a competitor product?",
  "groupIds": ["group-123"]
}

携带附件：

{
  "question": "Please review this product design and provide feedback",
  "attachments": [
    {
      "url": "https://example.com/design.pdf",
      "name": "Product Design v2",
      "type": "application/pdf"
    },
    {
      "path": "uploads/mockup.png",
      "name": "UI Mockup"
    }
  ],
  "links": [
    {
      "label": "https://competitor.com/product",
      "id": "link-1"
    }
  ],
  "keywords": [
    {
      "label": "sustainable packaging",
      "url": "https://example.com/article",
      "id": "keyword-1"
    }
  ]
}

参数说明

响应（Server-Sent Events）

该接口以 Server-Sent Events（SSE）流的形式返回数据，每个事件均为包含 type 字段的 JSON 对象。

问题分类

系统在处理前会自动将问题归类为以下三种类型之一：

对于开放式问题，响应会自动聚类为若干主题（例如"隐私顾虑"、"成本障碍"）。每条响应的 value 字段包含其所属主题。

事件类型

1. 开始事件

{"type": "start", "total": 10}

标志处理开始，并告知 minds 总数。

2. 分类事件

{
  "type": "classification",
  "classification": {
    "type": "scale",
    "scaleRange": [1, 5]
  }
}

说明问题的分类结果。量表类问题包含检测到的范围，分类类问题包含检测到的选项。

3. 回答事件

{
  "type": "answer",
  "sparkId": "spark-1",
  "sparkName": "Emma",
  "discipline": "College Student",
  "profileImageUrl": "https://...",
  "groupId": "group-123",
  "groupName": "Gen Z Consumers",
  "answer": "4\n\nI think this is a solid product but could improve..."
}

每个 mind 作答后单独推送。量表或分类类问题的回答以评分或选项开头，后跟推理说明。

4. 聚合中事件

{"type": "aggregating"}

表示 AI 正在聚合所有响应。对于开放式问题，此阶段包含主题聚类处理。

5. 结果事件

{
  "type": "result",
  "outputData": {
    "title": "What features would make you switch to a competitor product?",
    "type": "categorical",
    "classification": {
      "type": "categorical",
      "options": ["Yes", "No", "Maybe"]
    },
    "groups": [
      {
        "group": "Gen Z Consumers",
        "value": "Better Price",
        "alignmentScore": 82,
        "answers": [
          {
            "value": "Price",
            "persona": "Emma",
            "discipline": "College Student",
            "message": "I would switch if a competitor offered better pricing...",
            "imageUrl": "https://...",
            "reliabilityScore": 84
          }
        ]
      }
    ]
  },
  "outputType": "bar"
}

包含经分类处理的聚合结果。alignmentScore 和每条回答的 reliabilityScore 在 v1 接口返回结果前已完成计算（详见 Alignment 评分）。

6. 完成事件

{"type": "done"}

表示流式传输已结束。

输出数据结构

响应类型详解

量表响应：

• value：数值评分（例如 "4"）
• message：评分的简要推理
• groups[].value：该组的平均评分

分类响应：

• value：所选选项（例如 "Yes"、"Option A"）
• message：选择该项的简要推理
• groups[].value：该组中最多人选择的选项

开放式响应：

• value：所属主题（例如 "Privacy concerns"、"Cost barriers"）
• message：完整响应文本
• groups[].value：该组的主导主题
• 主题从所有响应中自动聚类生成（识别 3-6 个主题）

Alignment 评分

v1 API 响应中，每条 panel 回答包含两项评分：

• groups[].answers[].reliabilityScore（0-100，整数，可选）：衡量该 mind 的回答与其 systemPrompt 的人设契合度。采用与单个 spark 对话相同的评估器计算，因此 v1 panel 的值可直接与单 mind 的 reliabilityScore 进行横向比较。
• groups[].alignmentScore（0-100，整数，可选）：该组所有回答 reliabilityScore 的平均值。UI 将其显示为每组的 Alignment 指示器（High / Medium / Low）。

UI 使用的评级区间（不包含在响应载荷中，供 API 使用者对照参考）：

字段省略条件： 当 mind 的 systemPrompt 少于 20 个字符、回答消息为空，或评估器调用本身失败时，该条回答不参与评分。若某组内所有回答均被跳过，该组的 alignmentScore 也会省略。

时序说明： 在 v1 接口中，评分在返回响应前同步执行，因此评分结果与 outputData 其余内容一并返回。这会在 panel 生成的基础上增加数秒延迟。如需更快获取 panel 结果且不需要 Alignment 评分，建议在下游批量评估，而非依赖内联评分。

状态说明： 这是未来群组对齐指标（与实证研究结果的接近程度）的临时替代方案。字段名称在正式版本落地时将保持不变，但 alignmentScore 的语义可能会有所调整。

文件附件

你可以附加文件、链接和关键词，为 panel 问题提供背景信息。Minds 在作答前会接收到经过处理的内容。

附件类型

1. 文件附件（attachments）

上传文档、PDF、图片、电子表格供分析使用：

{
  "question": "What improvements would you suggest for this product spec?",
  "attachments": [
    {
      "url": "https://example.com/product-spec.pdf",
      "name": "Product Specification v2.1",
      "type": "application/pdf"
    },
    {
      "path": "uploads/user-research.docx",
      "name": "User Research Findings"
    }
  ]
}

支持的格式：

• 文档：PDF、DOCX、TXT、MD
• 图片：PNG、JPG、WEBP（支持 OCR）
• 电子表格：CSV、XLSX

文件来源：

• url：外部 URL（下载后处理）
• path：Supabase 存储路径（自动签名后处理）

2. 链接附件（links）

抓取并分析网页内容（对 JS 密集型网站使用 Firecrawl，并截图）：

{
  "question": "Compare our pricing to these competitors",
  "links": [
    { "label": "https://competitor-a.com/pricing", "id": "link-1" },
    { "label": "https://competitor-b.com/pricing", "id": "link-2" }
  ]
}

功能特性：

• JavaScript 渲染（Firecrawl）
• 截图捕获，提供视觉上下文
• Markdown 内容提取
• 自动内容截断（多链接时每条限 3000 字符，单链接时限 15000 字符）

3. 关键词上下文（keywords）

提供带来源 URL 的关键词，补充额外背景信息：

{
  "question": "How can we improve sustainability?",
  "keywords": [
    {
      "label": "circular economy",
      "url": "https://en.wikipedia.org/wiki/Circular_economy",
      "id": "kw-1"
    },
    {
      "label": "carbon neutral packaging",
      "url": "https://example.com/carbon-neutral-guide",
      "id": "kw-2"
    }
  ]
}

携带附件的完整示例

curl -X POST "https://getminds.ai/api/v1/panels/panel-id/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Based on this product design and competitor analysis, what features should we prioritize?",
    "groupIds": ["product-managers", "designers"],
    "attachments": [
      {
        "url": "https://example.com/product-design-v3.pdf",
        "name": "Product Design v3",
        "type": "application/pdf"
      }
    ],
    "links": [
      { "label": "https://competitor.com/features" }
    ],
    "keywords": [
      {
        "label": "user experience best practices",
        "url": "https://uxdesign.com/best-practices"
      }
    ]
  }'

处理流程：

• 文件并行分析（PDF 提取文本，图片进行 OCR/视觉识别）
• 链接通过 Firecrawl 抓取（JS 渲染加截图）
• 内容注入所有 minds 的问题上下文
• 附件处理失败时优雅降级，返回兜底消息

使用建议：

• 只附加与问题直接相关的文件（每个文件都会增加处理时间）
• 动态网页内容使用链接附件
• 补充网络背景信息使用关键词
• 文件处理超时：每个文件 30 秒
• 链接抓取超时：每个 URL 15 秒

请求示例

curl -X POST "https://getminds.ai/api/v1/panels/550e8400-e29b-41d4-a716-446655440000/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "On a scale of 1-10, how likely are you to recommend this product?"
  }'

示例：JavaScript EventSource

const eventSource = new EventSource(
  'https://getminds.ai/api/v1/panels/{panelId}/ask',
  {
    headers: {
      'Authorization': 'Bearer minds_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

// Note: For POST requests with SSE, use fetch with ReadableStream
const response = await fetch('https://getminds.ai/api/v1/panels/{panelId}/ask', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer minds_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    question: 'How satisfied are you with the current pricing?'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log('Event:', event.type, event);
    }
  }
}

错误响应

400 Bad Request - 缺少问题或未关联任何组

{
  "statusCode": 400,
  "message": "question is required"
}

{
  "statusCode": 400,
  "message": "No groups attached to this panel"
}

{
  "statusCode": 400,
  "message": "No minds in panel groups"
}

403 Forbidden - 无权访问该 panel

404 Not Found - Panel 不存在

模型覆盖

默认情况下，如果团队首选提供方已配置且有资格使用，panel 响应会使用该提供方；否则使用产品默认值。你可以在每次请求时覆盖模型和提供方，以便跨模型系列进行实验：

curl -X POST "https://getminds.ai/api/v1/panels/{panelId}/ask" \
  -H "Authorization: Bearer minds_…_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Rate this 1-5",
    "model": "gpt-4o",
    "provider": "openai"
  }'

支持的提供方：openai、anthropic、google。对于 panel 请求，model 和 provider 必须一起发送。如果只发送其中一个，API 会返回 400 Bad Request。每次请求的覆盖优先于团队提供方偏好。

禁用多样性检查

Panel 编排器在聚合前会执行一轮多样性强制再生成循环（二元组自相似度检测、值同质性检测、空桶填充），即 panel 流程的 L4 层。

如需在消融研究或基准测试中隔离该层的贡献，可传入 disableDiversityCheck: true：

curl -X POST "https://getminds.ai/api/v1/panels/{panelId}/ask" \
  -H "Authorization: Bearer minds_…_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What features matter most to you?",
    "disableDiversityCheck": true
  }'

启用该标志后，面板成员的响应将完全按初始生成结果返回，即使响应高度重叠也不会触发二次再生成。分类（L3）、单 spark RAG（L2）和聚合（L5）仍正常运行。成本节省：每个 panel 问题减少约 5-25% 的 LLM 调用次数，具体取决于多样性检查会标记多少个 sparks。

适用场景： 方法对比、编排层 A/B 测试、复现基线行为。生产环境的 panels 应保持默认关闭状态。

导出 Panel 结果

以 Markdown 格式生成所有 panel 结果的结构化报告。

接口： POST /api/v1/panels/{panelId}/export

请求头：

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

{
  "format": "md"
}

参数说明

响应

{
  "data": {
    "format": "md",
    "content": "# Panel Report: Consumer Research Panel\n\n## Executive Summary\n\nThis panel survey gathered insights from 15 participants across 3 consumer groups...\n\n## Methodology\n\n- 3 groups, 15 participants\n- 5 questions asked\n\n## Results by Question\n\n### Q1: How important is sustainability when choosing products?\n\n**Type:** scale\n\n#### Gen Z Consumers (dominant: Very Important)\n\n..."
  }
}

报告结构

生成的报告包含以下部分：

1. 执行摘要 - 2-3 段关键发现概述
2. 方法论 - 组别、参与者及结构说明
3. 逐题结果 - 跨组对比、关键洞察与引用
4. 跨组分析 - 各组之间的规律与趋势
5. 结论与建议 - 可落地的行动洞察

请求示例

curl -X POST "https://getminds.ai/api/v1/panels/550e8400-e29b-41d4-a716-446655440000/export" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "md"
  }'

错误响应

403 Forbidden - 无权访问该 panel

404 Not Found - Panel 不存在

查询导出状态

查询 panel 导出任务的状态。若未提供 jobId，则返回最近一次导出的状态。

接口： GET /api/v1/panels/{panelId}/export-status

请求头：

Authorization: Bearer minds_your_api_key

查询参数

响应

{
  "data": {
    "status": "completed",
    "downloadUrl": "/api/v1/panels/{panelId}/export-download?jobId=job-123"
  }
}

状态值说明

请求示例

curl -X GET "https://getminds.ai/api/v1/panels/{panelId}/export-status?jobId=job-123" \
  -H "Authorization: Bearer minds_your_api_key"

错误响应

403 Forbidden - 无权访问该 panel

404 Not Found - Panel 或任务不存在

下载导出文件

以 PDF 文件形式下载导出的 panel 报告。

接口： GET /api/v1/panels/{panelId}/export-download

请求头：

Authorization: Bearer minds_your_api_key

查询参数

响应

返回 PDF 文件，并附带以下响应头：

• Content-Type: application/pdf
• Content-Disposition: attachment; filename="Panel-Report.pdf"

请求示例

curl -X GET "https://getminds.ai/api/v1/panels/{panelId}/export-download?jobId=job-123" \
  -H "Authorization: Bearer minds_your_api_key" \
  -o panel-report.pdf

错误响应

400 Bad Request - 缺少 jobId 参数或任务尚未完成

403 Forbidden - 无权访问该 panel

404 Not Found - Panel 或任务不存在

完整工作流示例

以下是创建并使用 panel 的完整流程：

# 1. 先创建 spark 组（使用 Sparks API）
# 假设已创建 ID 为 group-genz 和 group-millennials 的组

# 2. 使用这些组创建 panel
curl -X POST "https://getminds.ai/api/v1/panels" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Pricing Research",
    "groupIds": ["group-genz", "group-millennials"]
  }'

# 响应：{ "data": { "id": "panel-123", ... } }

# 3. 向 panel 提问
curl -X POST "https://getminds.ai/api/v1/panels/panel-123/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What price point would you consider fair for this product?"
  }'

# 4. 继续提问
curl -X POST "https://getminds.ai/api/v1/panels/panel-123/ask" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How does this compare to competitor pricing?"
  }'

# 5. 导出结果报告
curl -X POST "https://getminds.ai/api/v1/panels/panel-123/export" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"format": "md"}'

# 6. 查询导出状态（轮询直至完成）
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-status" \
  -H "Authorization: Bearer minds_your_api_key"

# 响应：{ "data": { "status": "completed", "downloadUrl": "/api/v1/panels/panel-123/export-download?jobId=..." } }

# 7. 下载 PDF
curl -X GET "https://getminds.ai/api/v1/panels/panel-123/export-download?jobId=job-123" \
  -H "Authorization: Bearer minds_your_api_key" \
  -o panel-report.pdf

错误码汇总

后续步骤

• 创建 minds，填充你的 panel 组
• 了解身份认证
• 查阅错误与限制