麦喵开放 API - 让学习数据流动起来

麦喵开放 API 是一套完整的 HTTP 接口服务，让开发者、教师和内容创作者能够以编程方式与麦喵单词卡平台交互，实现卡片和卡组的自动化管理。

我能用 API 做什么？

👨‍🏫 教师场景

• 批量导入词汇：将 Excel/CSV 词表一键导入为麦喵卡组
• 自动生成学习内容：用 AI 批量生成带例句、发音的单词卡片
• 管理学习小组：批量查看学员学习进度，导出学习数据

🛠️ 开发者场景

• 开发辅助工具：制作词表转换器、内容生成插件
• 集成到教学平台：将麦喵卡片嵌入你的 LMS 系统
• 数据分析：获取学习数据，分析用户行为

📚 内容创作者场景

• 批量制作卡组：快速生成多个语种、多个主题的学习卡组
• 内容分发：将卡组内容同步到其他学习平台
• 建立内容库：程序化管理和更新你的单词内容

快速开始

1. 获取 API 访问权限

目前 API 处于内测阶段，如需使用请联系：

• 微信公众号：磊子 X 麦喵单词卡
• 微信：34805850

我们会为你开通接口权限并提供技术支持。

2. 下载开发工具包

为了方便使用，我们准备了以下资源：

3. 认证方式

Base URL: https://fc-mp-7c19cdfb-aa09-46b8-af6b-f7b52e3b3d7b.next.bspapp.com/open-api

App ID: __UNI__235AE90

用户认证（需要登录态的接口）:

uni-id-token: <用户登录凭证>
app-id: __UNI__235AE90

卡组认证（操作卡片的接口）:

cardGroupToken: <卡组访问凭证>

💡 快捷方式：如果你已经在麦喵小程序中创建了卡组，可以直接复制 cardGroupToken，无需走登录和创建卡组流程：

1. 打开麦喵小程序 → 进入卡组 → 点击"设置"
2. 找到「开放 API」选项 → 复制 cardGroupToken
3. 直接用这个 Token 调用创建卡片接口

各平台使用指南

🖥️ OpenClaw 平台

OpenClaw 支持从本地 skills 目录加载 skill，可以实现极简的自动化导入。

场景示例：基于卡组 Token 直接创建西班牙语卡片

如果你已有卡组，只需提供 cardGroupToken，AI 就能帮你完成复杂的卡片内容生成与导入。

1. 对话示例：

   "给这张卡组 Token：eyJhbGci... 导入 10 个春节相关的西班牙语单词，卡片内容尽量详细一些，我是西语新手。"

2. AI 处理过程： AI 会自动调用麦喵 Skill，生成带音标、词性、例句和翻译的详细内容，并直接同步到你的卡组。

使用方法：

1. 下载 Skill 包：memocard-api.zip

2. 解压到 OpenClaw skills 目录：

   # 方式1：解压到当前工作目录的 skills 文件夹
   unzip memocard-api.zip
   mv memocard-api /path/to/your/workspace/skills/
   
   # 方式2：解压到 OpenClaw 全局 skills 目录
   unzip memocard-api.zip -d ~/.openclaw/skills/
   

   或者直接复制已解压的 memocard-api 文件夹到任意 skills 目录。

3. 验证安装：

   openclaw skills list
   # 应该能看到 memocard-api
   

4. 开始使用： 告诉你的 AI 助手：

   "帮我用麦喵 API 批量导入这个 Excel 词表"

   AI 会自动：

   • 读取 memocard-api skill
   • 调用登录接口获取 token
   • 创建卡组
   • 批量导入卡片

快捷方式：直接复制 Token 如果你已经在麦喵小程序中创建了卡组，可以直接复制 Token，跳过登录流程：

1. 打开麦喵小程序 → 进入卡组 → 点击"设置"
2. 找到「开放 API」选项 → 复制 cardGroupToken
3. 直接用这个 Token 调用创建卡片接口

🤖 Coze 平台（扣子）

Coze 是一个强大的 AI Bot 开发平台，通过配置麦喵插件，可以实现从手写识别到自动入库的全流程。麦喵官方技能已在 Coze 上架：麦喵单词卡 AI 助手open in new window

视频演示：基于 Coze Skill + 卡组 Token 快速创建

在这个演示中，我们展示了如何直接利用已有的 cardGroupToken，让 Coze 助手快速生成内容并导入到指定卡组：

实战案例：基于手写单词识别并创建卡组

1. 场景描述：上传一张手写单词的照片，让 AI 自动识别并登录你的账号，创建新卡组并导入。
2. 全流程体验：
   • 用户：上传照片并提供账号信息（或已在 Bot 配置中预设）。
   • AI 识别：利用 OCR 插件识别手写内容。
   • 自动执行：
     1. 调用 /login 获取登录态。
     2. 调用 /createCardGroup 创建新卡组。
     3. 批量调用 /createCard 导入单词。

方法一：使用代码节点

1. 在 Bot 中添加「代码节点」
2. 复制 Python SDK 示例 中的代码
3. 修改为你需要的功能逻辑

方法二：使用插件

1. 创建自定义插件
2. 配置 API 端点：
   • 基础 URL: https://fc-mp-7c19cdfb-aa09-46b8-af6b-f7b52e3b3d7b.next.bspapp.com/open-api
   • 添加 Header: app-id: __UNI__235AE90
3. 定义每个接口的入参和出参
4. 在 Bot 工作流中调用

示例配置：

创建「创建卡片」插件：

• 请求方法: POST
• 请求地址: /createCard
• 请求头: app-id: __UNI__235AE90
• 请求参数:
  • cardGroupToken (string, 必填)
  • front (string, 必填)
  • back (string, 必填)
  • frontNote (string, 选填)
  • backNote (string, 选填)

获取 cardGroupToken：

1. 打开麦喵小程序 → 进入你的卡组 → 点击"设置"
2. 找到「开放 API」选项 → 复制 cardGroupToken
3. 在 Coze 插件配置中使用这个 Token

🧩 Dify / FastGPT / 其他平台

大部分 AI 平台都支持以下方式：

方式一：HTTP 请求节点

直接配置 HTTP 请求：

方法: POST
URL: https://fc-mp-7c19cdfb-aa09-46b8-af6b-f7b52e3b3d7b.next.bspapp.com/open-api/createCard
Headers:
  - app-id: __UNI__235AE90
  - Content-Type: application/json
Body:
  {
    "cardGroupToken": "{{cardGroupToken}}",
    "front": "{{front}}",
    "back": "{{back}}"
  }

方式二：导入 OpenAPI 规范

如果平台支持 OpenAPI/Swagger 导入，可以联系我们获取规范文件（微信：34805850）。

方式三：使用 Function Calling

在支持 Function Calling 的平台（如 OpenAI、Claude 等），直接提供 API 文档给 AI，它会自动生成函数调用。

📝 通用使用方法

如果你的平台不支持上述任何方式，可以直接使用 HTTP 调用：

import requests

BASE_URL = "https://fc-mp-7c19cdfb-aa09-46b8-af6b-f7b52e3b3d7b.next.bspapp.com/open-api"
APP_ID = "__UNI__235AE90"

# 创建卡片
response = requests.post(
    f"{BASE_URL}/createCard",
    headers={"app-id": APP_ID, "Content-Type": "application/json"},
    json={
        "cardGroupToken": "your-token",
        "front": "Hello",
        "back": "你好"
    }
)
print(response.json())

标准使用流程

完整流程（新用户）

1. 登录获取 token → POST /login
2. 创建卡组 → POST /createCardGroup  
3. 获取卡组访问凭证 → POST /getCardGroupOpenApiToken
4. 批量创建卡片 → POST /createCard

快捷流程（已有卡组）

如果你已经在麦喵小程序中创建了卡组：

1. 小程序内复制 cardGroupToken（卡组设置 → 开放 API）
2. 直接调用创建卡片 → POST /createCard

两种方式的区别：

• 完整流程：适合自动化脚本，全程通过 API 操作
• 快捷流程：适合已有卡组的老师，手动复制 Token 后开始批量导入

接口列表

用户管理

卡组管理

卡片管理

学习小组

使用示例

Python SDK

import requests

BASE_URL = "https://fc-mp-7c19cdfb-aa09-46b8-af6b-f7b52e3b3d7b.next.bspapp.com/open-api"
APP_ID = "__UNI__235AE90"

# 1. 登录
login_data = {
    "mobile": "13800138000",
    "password": "your-password"
}
response = requests.post(
    f"{BASE_URL}/login",
    headers={"app-id": APP_ID, "Content-Type": "application/json"},
    json=login_data
)
token = response.json()["data"]["token"]

# 2. 创建卡组
card_group_data = {
    "title": "英语四级词汇",
    "description": "大学英语四级核心词汇",
    "tags": ["英语", "四级"],
    "is_public": 1,
    "language": {"front": "en", "back": "zh"}
}
response = requests.post(
    f"{BASE_URL}/createCardGroup",
    headers={
        "uni-id-token": token,
        "app-id": APP_ID,
        "Content-Type": "application/json"
    },
    json=card_group_data
)
card_group_id = response.json()["data"]["id"]

# 3. 获取卡组 Token
response = requests.post(
    f"{BASE_URL}/getCardGroupOpenApiToken",
    headers={
        "uni-id-token": token,
        "app-id": APP_ID,
        "Content-Type": "application/json"
    },
    json={"cardGroupId": card_group_id}
)
card_group_token = response.json()["data"]["token"]

# 4. 批量创建卡片
words = [
    ("abandon", "放弃，抛弃"),
    ("ability", "能力，才能"),
    ("absent", "缺席的，不在场的"),
]

for front, back in words:
    requests.post(
        f"{BASE_URL}/createCard",
        headers={"app-id": APP_ID, "Content-Type": "application/json"},
        json={
            "cardGroupToken": card_group_token,
            "front": front,
            "back": back
        }
    )

cURL 示例

# 创建卡片
curl --location --request POST 'https://fc-mp-7c19cdfb-aa09-46b8-af6b-f7b52e3b3d7b.next.bspapp.com/open-api/createCard' \
  --header 'app-id: __UNI__235AE90' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "front": "Hello",
    "back": "你好",
    "cardGroupToken": "your-token-here"
  }'

实战案例

案例 1：Excel 词表导入

场景：老师有 500 个雅思词汇的 Excel 表格，想导入麦喵

解决方案：

1. 将 Excel 另存为 CSV 格式
2. 使用 批量导入工具 一键导入
3. 或使用 Python SDK 自定义导入逻辑
4. 生成分享链接给学生

查看详细教程 →

案例 2：AI 生成学习内容

场景：用 AI 批量生成带例句、同义词、反义词的单词卡片

解决方案：

1. 提供词表给 AI
2. AI 生成丰富的学习内容（单词 + 释义 + 例句 + 词性）
3. 导出为 CSV 格式
4. 使用批量导入工具导入麦喵
5. 一次性生成上百张高质量卡片

案例 3：学习数据同步

场景：将麦喵学习数据同步到学校的 LMS 系统

解决方案：

1. 调用 /getAllCard 获取卡组内容
2. 调用 /getAllUnfamiliarCard 获取学生薄弱点
3. 调用 /getUserList 获取学习小组数据
4. 同步到你的数据分析平台

错误码说明

常见问题

Q: API 是免费的吗？

目前 API 处于内测阶段，对合作伙伴免费开放。正式上线后会有合理的调用配额和定价方案。

Q: 可以创建多少个卡组和卡片？

目前没有硬性限制，但建议合理使用，避免短时间内大量请求。

Q: Token 会过期吗？

用户登录 token 有过期时间，卡组 Token 长期有效（除非主动重置）。

Q: 支持哪些编程语言？

API 是标准 HTTP 接口，任何能发起 HTTP 请求的语言都可以使用。我们提供了 Python 示例。

Q: 我的平台不在上面列表里怎么办？

只要是支持 HTTP 请求的平台都可以使用。参考「通用使用方法」或联系我们（微信：34805850）获取技术支持。

获取帮助

遇到问题？我们提供多种支持渠道：

• 💬 微信公众号：磊子 X 麦喵单词卡
• 💬 微信：34805850（备注：API）
• 📖 文档：www.memocard.cnopen in new window

欢迎加入麦喵开发者社群，与其他开发者交流经验！

开始构建你的学习工具吧！ 🚀