secondme-reference
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSecondMe API 技术参考
SecondMe API Technical Reference
本文档包含 SecondMe API 的完整技术参考信息,供开发时查阅。
This document contains complete technical reference information for the SecondMe API, for reference during development.
API 基础 URL
API Base URL
https://app.mindos.com/gate/labhttps://app.mindos.com/gate/labOAuth2 授权 URL
OAuth2 Authorization URL
https://go.second.me/oauth/https://go.second.me/oauth/OAuth2 流程
OAuth2 Flow
1. 用户点击登录 → 跳转到 SecondMe 授权页面
2. 用户授权 → 重定向回你的应用(带 authorization_code)
3. 后端用 code 换取 access_token 和 refresh_token
4. 使用 access_token 调用 SecondMe API
5. Token 过期时使用 refresh_token 刷新1. User clicks Login → Redirect to SecondMe authorization page
2. User authorizes → Redirect back to your application (with authorization_code)
3. Backend exchanges code for access_token and refresh_token
4. Call SecondMe API using access_token
5. Refresh with refresh_token when Token expiresToken 有效期
Token Validity Period
| Token 类型 | 前缀 | 有效期 |
|---|---|---|
| 授权码 | | 5 分钟 |
| Access Token | | 2 小时 |
| Refresh Token | | 30 天 |
| Token Type | Prefix | Validity Period |
|---|---|---|
| Authorization Code | | 5 minutes |
| Access Token | | 2 hours |
| Refresh Token | | 30 days |
权限列表(Scopes)
Permission List (Scopes)
| 权限 | 说明 |
|---|---|
| 用户基础信息 |
| 用户兴趣标签 |
| 用户软记忆 |
| 添加笔记 |
| 聊天功能 |
| 结构化动作判断(Act) |
| Scope | Description |
|---|---|
| Basic user information |
| User interest tags |
| User soft memory |
| Add notes |
| Chat functionality |
| Structured action judgment (Act) |
API 响应格式与处理
API Response Format and Handling
重要:所有 SecondMe API 响应都遵循统一格式:
json
{
"code": 0,
"data": { ... } // 实际数据在 data 字段内
}前端代码必须正确提取数据:
typescript
// 注意:以下 /api/secondme/... 是 Next.js 本地路由(由 secondme-nextjs skill 生成),
// 本地路由会代理请求到上游 SecondMe API,并透传上游的响应格式。
// ❌ 错误写法 - 直接使用响应会导致 .map is not a function
const response = await fetch('/api/secondme/user/shades'); // Next.js 本地路由
const shades = await response.json();
shades.map(item => ...) // 错误!
// ✅ 正确写法 - 提取 data 字段内的数据
const response = await fetch('/api/secondme/user/shades'); // Next.js 本地路由
const result = await response.json();
if (result.code === 0) {
const shades = result.data.shades; // 正确!
shades.map(item => ...)
}Important: All SecondMe API responses follow a unified format:
json
{
"code": 0,
"data": { ... } // Actual data is in the data field
}Frontend code must extract data correctly:
typescript
// Note: The following /api/secondme/... is a Next.js local route (generated by secondme-nextjs skill),
// which proxies requests to the upstream SecondMe API and passes through the upstream response format.
// ❌ Wrong approach - Directly using the response will cause .map is not a function
const response = await fetch('/api/secondme/user/shades'); // Next.js local route
const shades = await response.json();
shades.map(item => ...) // Error!
// ✅ Correct approach - Extract data from the data field
const response = await fetch('/api/secondme/user/shades'); // Next.js local route
const result = await response.json();
if (result.code === 0) {
const shades = result.data.shades; // Correct!
shades.map(item => ...)
}各 API 的数据路径
Data Paths for Each API
以下路径均为上游 SecondMe API 路径,完整 URL =其中{base_url}/api/secondme{path}来自base_url(默认state.api.base_url)https://app.mindos.com/gate/lab
| 上游 API 路径 | 数据路径 | 类型 |
|---|---|---|
| | object(含 email, name, avatarUrl, route 等字段) |
| | array |
| | array |
| | array |
| | array |
| SSE 流式 JSON(需拼接 delta) | SSE stream |
| | number |
The following paths are upstream SecondMe API paths, complete URL =Where{base_url}/api/secondme{path}comes frombase_url(defaultstate.api.base_url)https://app.mindos.com/gate/lab
| Upstream API Path | Data Path | Type |
|---|---|---|
| | object (contains fields like email, name, avatarUrl, route, etc.) |
| | array |
| | array |
| | array |
| | array |
| SSE streaming JSON (needs delta concatenation) | SSE stream |
| | number |
Act API(结构化动作判断)
Act API (Structured Action Judgment)
Act API 是独立于 Chat API 的接口,约束模型仅输出合法 JSON 对象,适用于情感分析、意图分类等结构化决策场景。权限使用 scope。
chatThe Act API is an interface independent of the Chat API, which restricts the model to output only valid JSON objects. It is suitable for structured decision-making scenarios such as sentiment analysis and intent classification. It uses the scope for permissions.
chat端点(上游 API)
Endpoint (Upstream API)
POST {base_url}/api/secondme/act/streamPOST {base_url}/api/secondme/act/stream请求参数
Request Parameters
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
| message | string | 是 | 用户消息内容 |
| actionControl | string | 是 | 动作控制说明(20-8000 字符),定义 JSON 结构与判断规则 |
| appId | string | 否 | 应用 ID |
| sessionId | string | 否 | 会话 ID,不提供则自动生成 |
| systemPrompt | string | 否 | 系统提示词,仅新会话首次有效 |
| Parameter | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | User message content |
| actionControl | string | Yes | Action control instructions (20-8000 characters), defining JSON structure and judgment rules |
| appId | string | No | Application ID |
| sessionId | string | No | Session ID, automatically generated if not provided |
| systemPrompt | string | No | System prompt, only valid for the first time in a new session |
actionControl 示例
actionControl Example
仅输出合法 JSON 对象,不要解释。
输出结构:{"is_liked": boolean}。
当用户明确表达喜欢或支持时 is_liked=true,否则 is_liked=false。Only output valid JSON objects, no explanations.
Output structure: {"is_liked": boolean}.
Set is_liked=true when the user clearly expresses liking or support, otherwise is_liked=false.响应格式(SSE)
Response Format (SSE)
event: session
data: {"sessionId": "labs_sess_xxx"}
data: {"choices": [{"delta": {"content": "{\"is_liked\": true}"}}]}
data: [DONE]event: session
data: {"sessionId": "labs_sess_xxx"}
data: {"choices": [{"delta": {"content": "{\"is_liked\": true}"}}]}
data: [DONE]前端处理示例
Frontend Handling Example
typescript
// 调用 Act API 进行结构化判断(通过 Next.js 本地路由代理到上游)
const response = await fetch('/api/secondme/act/stream', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: userMessage,
actionControl: '仅输出合法 JSON。结构:{"intent": "like"|"dislike"|"neutral"}。根据用户表达判断意图。信息不足时返回 {"intent": "neutral"}。'
})
});
// 拼接 SSE 流中的 delta content,最终 JSON.parse 得到结果typescript
// Call Act API for structured judgment (proxied to upstream via Next.js local route)
const response = await fetch('/api/secondme/act/stream', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
message: userMessage,
actionControl: 'Only output valid JSON. Structure: {"intent": "like"|"dislike"|"neutral"}. Judge intent based on user expression. Return {"intent": "neutral"} when information is insufficient.'
})
});
// Concatenate delta content in the SSE stream, then JSON.parse to get the resultChat vs Act 使用场景
Chat vs Act Usage Scenarios
| 场景 | 使用 API | 原因 |
|---|---|---|
| 自由对话 | | 返回自然语言文本 |
| 情感/意图判断 | | 返回结构化 JSON |
| 是/否决策 | | 返回 |
| 多分类判断 | | 返回 |
| 内容生成 | | 需要长文本输出 |
| Scenario | API to Use | Reason |
|---|---|---|
| Free conversation | | Returns natural language text |
| Sentiment/intent judgment | | Returns structured JSON |
| Yes/no decision making | | Returns |
| Multi-category judgment | | Returns |
| Content generation | | Requires long text output |
开发注意事项
Development Notes
State 参数
State Parameter
直接忽略 参数验证。 在回调处理时不需要验证 state,直接处理授权码即可。
stateIgnore the parameter validation directly. There is no need to validate the state during callback processing; just process the authorization code directly.
stateCSS @import 规则顺序
CSS @import Rule Order
重要: 在 CSS 文件中, 语句必须放在文件的最开头(只能在 和 之后)。如果在其他 CSS 规则之后使用 ,会导致解析错误。
@import@charset@layer@importcss
/* 正确写法 - @import 放在最前面 */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC&display=swap');
:root {
--primary-color: #000;
}
/* 错误写法 - @import 不能放在其他规则之后 */
:root {
--primary-color: #000;
}
@import url('...'); /* 这会报错! */Important: In CSS files, statements must be placed at the very beginning of the file (only after and ). Using after other CSS rules will cause parsing errors.
@import@charset@layer@importcss
/* Correct approach - @import placed at the top */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC&display=swap');
:root {
--primary-color: #000;
}
/* Wrong approach - @import cannot be placed after other rules */
:root {
--primary-color: #000;
}
@import url('...'); /* This will cause an error! */官方文档链接
Official Document Links
| Document | URL |
|---|---|
| Quick Start | https://develop-docs.second.me/zh/docs |
| Authentication Overview | https://develop-docs.second.me/zh/docs/authentication |
| OAuth2 Guide | https://develop-docs.second.me/zh/docs/authentication/oauth2 |
| SecondMe API Reference | https://develop-docs.second.me/zh/docs/api-reference/secondme |
| OAuth2 API Reference | https://develop-docs.second.me/zh/docs/api-reference/oauth |
| Error Code Reference | https://develop-docs.second.me/zh/docs/errors |