Sparks API

以编程方式创建和管理 AI Minds(agent)。Minds 是具备特定专长、个性与知识的可定制 AI 助手。

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

获取 Spark

获取单个 mind 的完整详情,包含 system prompt、共享设置以及知识条目数量。

Endpoint: GET /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

响应

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Expert",
    "description": "Experienced marketing director",
    "type": "expert",
    "discipline": "Marketing",
    "systemPrompt": "## Core Identity & Personality\n\nYou are a seasoned marketing director...",
    "tags": ["marketing", "b2b"],
    "isPublic": false,
    "isLinkSharingEnabled": false,
    "publicShareId": null,
    "profileImageUrl": "https://...",
    "phoneNumber": null,
    "clonedVoiceStatus": null,
    "profitSplitOptIn": false,
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z",
    "knowledgeItemCount": 12
  }
}

响应字段

请求示例

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

错误响应

400 Bad Request - spark ID 格式无效

401 Unauthorized - API key 无效或缺失

403 Forbidden - 无权访问此 mind

404 Not Found - Mind 不存在

列出 Spark

获取已认证用户拥有的所有 mind。

Endpoint: GET /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key

查询参数

响应

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Expert",
      "description": "Experienced marketing director",
      "type": "expert",
      "discipline": "Marketing",
      "tags": ["marketing", "b2b"],
      "profileImageUrl": "https://...",
      "createdAt": "2025-12-10T12:00:00.000Z",
      "updatedAt": "2025-12-10T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 100,
    "offset": 0
  }
}

响应字段

请求示例

curl -X GET "https://getminds.ai/api/v1/sparks?limit=10&offset=0" \
  -H "Authorization: Bearer minds_your_api_key"

创建 Spark

使用不同训练模式以自定义配置创建新的 AI mind。

Endpoint: POST /api/v1/sparks

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

{
  "name": "My AI Expert",
  "description": "An expert in renewable energy",
  "mode": "keywords",
  "type": "expert",
  "discipline": "Renewable Energy",
  "keywords": ["solar", "wind energy", "sustainability", "green tech"],
  "personaContext": "Ada Lovelace, pioneering computer scientist",
  "contextLink": "https://example.com/profile",
  "tags": ["energy", "solar", "sustainability"],
  "profileImageUrl": "https://example.com/avatar.jpg"
}

参数

Mode 取值

mode 参数决定你的 mind 如何训练:

• keywords(默认)- 使用逗号分隔的关键词训练 mind。AI 将基于这些关键词从不同来源收集相关信息,以构建 mind 的知识库。
  • 必填字段: keywords - 关键词/主题数组
  • 最适合: 特定主题或领域的通用专业能力
• clone - 通过提供某人的名称和上下文来克隆其风格与知识。AI 将研究并构建模仿其专业能力和沟通风格的完整 profile。
  • 必填字段: personaContext - 名称及简要上下文(例如 "Ada Lovelace, pioneering computer scientist")
  • 最适合: 模仿特定个人、历史人物或知名专家
• link - 使用特定 URL 的内容训练 mind。提供 profile、作品集或网站链接,AI 将分析并提取相关信息。
  • 必填字段: contextLink - 内容源 URL
  • 最适合: 基于特定网站、作品集或在线 profile 进行训练
• manual - 创建不进行自动训练的 mind。你将手动配置所有设置,并稍后通过 knowledge API 添加知识。
  • 无额外必填字段
  • 最适合: 希望完全控制训练数据的自定义配置

自动处理: 当你使用 keywords、clone 或 link 时,后端行为与产品内 Add Spark 表单一致 —— 派生 entity 关键词(clone/link 使用 AI 辅助)并异步训练该 mind。可通过创建响应中的 training 区块以及下文 Mind 训练生命周期 中描述的专用端点来跟踪训练进度。manual 模式跳过该自动化,以便你稍后通过 Knowledge API 进行训练。

Type 取值

• creative - 面向艺术家、设计师、作家等创意工作者
• expert - 面向专家、顾问及领域专家
• user - 面向用户 persona、客户与目标受众原型

响应

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My AI Expert",
    "description": "An expert in renewable energy",
    "type": "expert",
    "discipline": "Renewable Energy",
    "tags": ["energy", "solar", "sustainability"],
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-10T12:00:00.000Z"
  },
  "training": {
    "status": "queued",
    "readyToChat": false,
    "message": "Queued for data collection",
    "startedAt": null,
    "completedAt": null,
    "error": null
  }
}

training 区块报告 mind 在创建时的生命周期。keywords、clone 和 link 模式以 queued 开始并在后台训练;manual mind 返回时即为 completed,且 readyToChat 已为 true。mind 的 id 在此调用返回时即存在,但只有当 readyToChat 为 true 时该 mind 才能作答。轮询方式见下文 Mind 训练生命周期。

示例:使用 Keywords 模式创建 Mind

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing Expert",
    "description": "Experienced marketing director with expertise in B2B SaaS",
    "mode": "keywords",
    "type": "expert",
    "discipline": "Marketing",
    "keywords": ["B2B marketing", "SaaS", "growth marketing", "content strategy", "brand positioning", "ROI"],
    "tags": ["marketing", "b2b", "saas", "growth"]
  }'

示例:使用 Clone 模式创建 Mind

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace AI",
    "description": "AI trained to emulate Ada Lovelace",
    "mode": "clone",
    "type": "expert",
    "discipline": "Computer Science Pioneer",
    "personaContext": "Ada Lovelace, pioneering computer scientist and mathematician, first computer programmer",
    "tags": ["computer science", "mathematics", "history"]
  }'

示例:使用 Link 模式创建 Mind

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Voice Expert",
    "description": "Trained on company brand guidelines",
    "mode": "link",
    "type": "creative",
    "discipline": "Brand Strategy",
    "contextLink": "https://example.com/brand-guidelines",
    "tags": ["branding", "copywriting"]
  }'

示例:使用 Manual 模式创建 Mind

curl -X POST "https://getminds.ai/api/v1/sparks" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Assistant",
    "description": "Custom configured assistant",
    "mode": "manual",
    "type": "creative",
    "discipline": "General Assistant",
    "tags": ["custom"]
  }'

Mind 训练生命周期

创建 mind 是异步的。POST /v1/sparks 会立即返回一个 id,但对于 keywords、clone 和 link 模式,mind 仍在后台训练。mind 的 id 存在并不意味着该 mind 已就绪 —— 只有当 readyToChat 为 true 时该 mind 才能作答。唯一的例外是 manual 模式:这类 mind 跳过数据收集,在创建的那一刻即为 completed。

轮询专用的训练端点,直到 mind 就绪:

curl "https://getminds.ai/api/v1/sparks/{sparkId}/training" \
  -H "Authorization: Bearer minds_your_api_key"

{
  "status": "running",
  "readyToChat": false,
  "message": "Collecting knowledge...",
  "startedAt": "2025-12-10T12:00:01.000Z",
  "completedAt": null,
  "error": null
}

状态值

GET /v1/sparks/{id} 也会随 mind 的其余信息一起返回 readyToChat(和 trainingStatus),因此一次读取即可同时告诉你该 mind 是谁以及它是否已能作答。

训练失败时

当 status 为 failed 时,响应会包含一个带有 code 和 retryable 标志的 error 对象:

重新训练

如果某个 mind 以 failed 结束(或你只是想重建一个 completed 的 mind),可重新训练它:

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/retrain" \
  -H "Authorization: Bearer minds_your_api_key"

这会将该 mind 重新入队,并返回一个 status 为 queued 的全新 training 区块。重新训练仅对已完成的 mind 有效:仍处于 queued 或 running 的 mind 会返回 409 Conflict,因为已有一次训练正在进行。重新训练后,请再次轮询 GET /v1/sparks/{id}/training,直到 readyToChat 为 true。

头像图片

当你提供 profileImageUrl 时:

1. 图片从外部 URL 下载
2. 上传到安全存储
3. 响应中返回存储后的 URL

支持的格式:JPG、PNG、GIF、WEBP

训练原理

系统根据你选择的 mode、type 和 discipline 自动生成智能 system prompt:

• Keywords 模式:围绕你指定的关键词构建专业能力
• Clone 模式:构建模仿指定人物风格与知识的 profile
• Link 模式:从所提供的 URL 提取知识
• Manual 模式:创建一个基础助手,你将使用自定义知识进行训练

你可以在创建后 上传知识 进一步增强 mind。

计划限制

不同计划有不同的 mind 创建上限:

达到上限时,你将收到 403 Forbidden 错误:

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

错误响应

400 Bad Request

参数缺失或无效。

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

401 Unauthorized

API key 无效或缺失。

403 Forbidden

达到计划限制。

500 Internal Server Error

服务器端错误(罕见)。

更新 Spark

更新已存在 mind 的配置,包括名称、描述、system prompt 及其他设置。

Endpoint: PUT /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key
Content-Type: application/json

请求体

{
  "name": "Updated Name",
  "description": "Updated description",
  "type": "expert",
  "discipline": "Updated Discipline",
  "systemPrompt": "Custom system prompt instructions...",
  "tags": ["tag1", "tag2"],
  "isPublic": false
}

参数

System Prompt

systemPrompt 字段允许你自定义 mind 的行为与响应方式。适用于:

• Persona 自定义:定义特定的人格特征、沟通风格或专业领域
• 响应格式:指示 mind 以特定格式回答(例如点列表、编号列表)
• 领域约束:将响应限制在特定主题或视角
• 语言/语调:设定响应的语言、正式程度或语调

System prompt 示例:

# Survey Response Expert
Du bist ein erfahrener Handwerker. Bei Umfragen antworte immer aus deiner
persönlichen Erfahrung, nicht mit allgemeinen Branchendurchschnittswerten.
Wähle bei Multiple-Choice-Fragen immer genau eine Option.

# Technical Expert
You are a senior software architect. Always provide concrete,
actionable advice. Include code examples when relevant.
Avoid vague statements.

响应

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Name",
    "description": "Updated description",
    "type": "expert",
    "discipline": "Updated Discipline",
    "systemPrompt": "Custom system prompt...",
    "tags": ["tag1", "tag2"],
    "isPublic": false,
    "profileImageUrl": "https://...",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "updatedAt": "2025-12-29T15:30:00.000Z"
  }
}

示例:更新 System Prompt

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "Du bist ein erfahrener Handwerker im Sanitärbereich. Antworte immer aus deiner persönlichen Praxiserfahrung."
  }'

示例:更新多个字段

curl -X PUT "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Plumber Expert",
    "description": "Expert plumber with 20 years of experience",
    "discipline": "Plumbing & Sanitary Installation",
    "tags": ["plumbing", "sanitary", "renovation"]
  }'

错误响应

400 Bad Request - 无有效字段可更新或字段值无效

401 Unauthorized - API key 无效或缺失

403 Forbidden - 无权更新此 mind(必须是 owner)

404 Not Found - Mind 不存在

获取 Spark 知识模式

获取特定 mind 按框架组织的思维模式与知识。

Endpoint: GET /api/v1/sparks/{sparkId}/knowledge/patterns

Headers:

Authorization: Bearer minds_your_api_key

响应结构

该 endpoint 返回按框架分组的模式(例如 AOX Internal、OCEAN、DISC 等),其中的方法与能力包含出现次数与证据。

{
  "success": true,
  "data": {
    "sparkId": "550e8400-e29b-41d4-a716-446655440000",
    "sparkName": "Marketing Expert",
    "totalPatterns": 47,
    "frameworks": [
      {
        "id": "aox-internal",
        "name": "AOX Internal Framework",
        "totalOccurrences": 32,
        "methods": [
          {
            "id": "strategic-thinking",
            "name": "Strategic Thinking",
            "description": "Ability to think strategically and plan long-term",
            "occurrences": 15,
            "competencies": [
              {
                "id": "market-analysis",
                "name": "Market Analysis",
                "description": "Understanding market dynamics and trends",
                "occurrences": 8,
                "evidence": [
                  {
                    "spark": "Market segmentation requires understanding customer pain points and aligning product features with specific needs...",
                    "portfolioItemId": "abc-123",
                    "createdAt": "2025-12-10T15:30:00.000Z"
                  },
                  {
                    "spark": "Competitive analysis shows that timing and positioning are critical for market entry...",
                    "portfolioItemId": "def-456",
                    "createdAt": "2025-12-10T14:20:00.000Z"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

理解响应

• frameworks:包含该 spark 模式的框架数组
  • totalOccurrences:该框架下的模式总数
  • methods:检测到的思维方法或路径
    • occurrences:该方法出现的次数
    • competencies:该方法下的具体技能或子领域
      • occurrences:该能力下的模式数量
      • evidence:展示该模式的引用/片段数组
        • spark:内容中的实际片段或洞察
        • portfolioItemId:源材料引用
        • createdAt:该模式被识别的时间

请求示例

curl -X GET "https://getminds.ai/api/v1/sparks/{sparkId}/knowledge/patterns" \
  -H "Authorization: Bearer minds_your_api_key"

使用场景

• 了解 mind 的专业能力:查看你的 mind 已学到哪些方法与能力
• 质量保障:验证模式是否正确从训练数据中提取
• 知识缺口:识别需要更多训练数据的领域
• 框架对比:比较一个 mind 在不同框架下的表现

错误响应

401 Unauthorized - API key 无效或缺失

403 Forbidden - 无权访问此 mind

404 Not Found - Mind 不存在

重新生成 System Prompt

使用 spark 的现有知识库重新生成全部 system prompt 组件。该过程使用与 UI 中 "Generate All" 按钮相同的 AI 生成逻辑。

Endpoint: POST /api/v1/sparks/{sparkId}/regenerate-prompt

Headers:

Authorization: Bearer minds_your_api_key

工作原理

该 endpoint 分析 mind 的知识库(portfolio items、patterns、embeddings)并生成全部 prompt 组件:

对于 user 类型 spark:

• Core Identity & Demographics
• Needs & Motivations
• Pain Points & Challenges
• Tone & Communication Style
• Goals & Desires
• Behavioral Patterns

对于 expert 类型 spark:

• Core Identity & Personality
• Professional Expertise & Credentials
• Tone & Communication Style
• Professional Approach & Methods
• Domain Knowledge

对于 creative 类型 spark:

• Core Identity & Personality
• Creative Philosophy & Values
• Tone & Communication Style
• Creative Approach & Methods
• Domain Expertise

响应

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Spark",
    "systemPrompt": "## Core Identity & Demographics\n\n...",
    "promptLength": 2847
  }
}

请求示例

curl -X POST "https://getminds.ai/api/v1/sparks/{sparkId}/regenerate-prompt" \
  -H "Authorization: Bearer minds_your_api_key"

使用场景

• 添加知识之后:重新生成 prompt 以纳入新添加的知识条目
• Persona 调优:基于当前知识模式更新 persona
• 重置自定义内容:清除手动编辑内容,并基于知识库重新生成 prompt

错误响应

401 Unauthorized - API key 无效或缺失

403 Forbidden - 无权修改此 mind(必须是 owner)

404 Not Found - Mind 不存在

500 Internal Server Error - 生成 prompt 失败(例如知识不足)

删除 Spark

永久删除 mind 及所有相关数据,包括知识、portfolio 条目和文件。

Endpoint: DELETE /api/v1/sparks/{sparkId}

Headers:

Authorization: Bearer minds_your_api_key

响应

成功时返回 204 No Content,响应体为空。

请求示例

curl -X DELETE "https://getminds.ai/api/v1/sparks/{sparkId}" \
  -H "Authorization: Bearer minds_your_api_key"

哪些内容会被删除

删除 mind 时,以下内容会被永久删除:

• Mind 本身及其所有配置
• 所有知识与训练数据
• 所有 portfolio 条目及关联文件
• 所有聊天历史与消息
• 头像与已上传文件

警告: 此操作无法撤销。

错误响应

400 Bad Request - spark ID 格式无效

401 Unauthorized - API key 无效或缺失

403 Forbidden - 无权删除此 mind(必须是 owner)

404 Not Found - Mind 不存在

下一步

• 为 mind 上传知识
• 与 mind 聊天
• 了解 错误与限制