API 参考

本文档提供单词记忆卡片 API 的完整技术参考,包括端点说明、请求参数、响应格式和限速规则。


GET/api/public/memory-card

端点信息

查询单词的记忆卡片数据。返回包含例句、词组、助记技巧等丰富内容的记忆卡片。

请求参数

  • Name
    word
    Type
    string
    Description

    要查询的单词,长度 1-100 个字符。会自动转换为小写。

  • Name
    lang
    Type
    string
    Description

    语言代码,默认为 en。支持的语言包括:en(英语)、es(西班牙语)、ja(日语)、de(德语)、fr(法语)等。

响应头

  • Name
    X-RateLimit-Limit
    Type
    integer
    Description

    每日总请求限额(默认 150)

  • Name
    X-RateLimit-Remaining
    Type
    integer
    Description

    今日剩余请求次数

  • Name
    X-RateLimit-Reset
    Type
    string
    Description

    限额重置时间(ISO 8601 格式)

  • Name
    Cache-Control
    Type
    string
    Description

    缓存控制:public, max-age=86400(24小时)

请求示例

curl -G https://api.keykey.cc/api/public/memory-card \
  -d word=hello \
  -d lang=en

成功响应 (200)

{
  "success": true,
  "data": {
    "word": "hello",
    "languageCategory": "en",
    "phonetic": "/həˈloʊ/",
    "examples": [
      {
        "sentence": "Hello, how are you doing today?",
        "translation": "你好,今天过得怎么样?",
        "usage": "非常常见的问候语,用于打招呼并询问对方近况。"
      },
      {
        "sentence": "Hello! Is anyone there?",
        "translation": "喂!有人在吗?",
        "usage": "在电话接通、敲门或进入一个陌生空间时,用来引起注意或确认是否有人。"
      },
      {
        "sentence": "Hello, Sarah! Nice to see you again.",
        "translation": "你好,莎拉!很高兴再次见到你。",
        "usage": "用于熟人之间,表达见到对方的喜悦。"
      }
    ],
    "phrases": [
      {
        "phrase": "Hello there!",
        "translation": "你好呀!",
        "usage": "比"Hello"更热情、更友好的问候方式,常用于见到认识的人。"
      },
      {
        "phrase": "Hello-hello?",
        "translation": "喂?喂?",
        "usage": "在电话中,当听不清对方声音或想确认对方是否还在时使用。"
      }
    ],
    "mnemonics": "想象一下,你正在招手(hand)向别人打招呼,然后说"噢,你好!"(Oh, low! 听起来有点像hello)。",
    "synonyms": [
      {
        "word": "Hi",
        "difference": "比 'hello' 更随意、更口语化,适合非正式场合。"
      },
      {
        "word": "Hey",
        "difference": "非常口语化,常用于引起注意或打招呼,比 'hi' 更随意,有时也带有惊喜或疑问的语气。"
      },
      {
        "word": "Greetings",
        "difference": "比较正式的问候语,常用于书面语或正式场合,不如 'hello' 常用。"
      }
    ],
    "usageScenes": [
      "初次见面打招呼",
      "日常问候(朋友、家人、同事)",
      "接听电话",
      "引起他人注意",
      "网络聊天开场白"
    ],
    "cached": true
  },
  "rateLimit": {
    "remaining": 499,
    "limit": 150,
    "reset": "2025-10-24T00:00:00.000Z"
  }
}

数据字段说明

MemoryCardData

  • Name
    word
    Type
    string
    Description

    单词原文(小写)

  • Name
    languageCategory
    Type
    string
    Description

    语言代码

  • Name
    phonetic
    Type
    string
    Description

    音标 部分单词没有音标(可选)

  • Name
    examples
    Type
    array
    Description

    例句列表,每个例句包含 sentence(英文)、translation(翻译)、usage(用法说明,可选)

  • Name
    phrases
    Type
    array
    Description

    词组搭配列表(可选),每个词组包含 phrase、translation、usage

  • Name
    mnemonics
    Type
    string
    Description

    助记技巧(可选)

  • Name
    etymology
    Type
    string
    Description

    词根词缀分析(可选)

  • Name
    synonyms
    Type
    array
    Description

    同义词辨析列表(可选),每个包含 word 和 difference

  • Name
    usageScenes
    Type
    array
    Description

    使用场景列表(可选)

  • Name
    cached
    Type
    boolean
    Description

    是否来自缓存

数据示例

{
  "word": "study",
  "languageCategory": "en",
  "examples": [
    {
      "sentence": "She decided to study abroad for a year to improve her language skills.",
      "translation": "她决定出国留学一年以提高她的语言能力。",
      "usage": "描述为了提升某项技能或达成特定目标而进行的学习行为。"
    },
    {
      "sentence": "The students are busy studying for their final exams.",
      "translation": "学生们正忙于为期末考试复习。",
      "usage": "强调为考试而进行的集中学习或复习。"
    }
  ],
  "synonyms": [
    {
      "word": "learn",
      "difference": "'Learn' 更侧重于获取知识或技能的过程,而 'study' 强调通过刻意努力来学习。"
    },
    {
      "word": "research",
      "difference": "'Research' 通常指为了发现新知识或验证现有理论而进行的系统性、深入的探究,比 'study' 更具探索性和科学性。"
    },
    {
      "word": "read",
      "difference": "'Read' 仅仅是阅读文字的过程,而 'study' 包含了阅读、理解、思考、分析等更深层次的学习过程。"
    }
  ],
  "usageScenes": [
    "学术学习(学校、大学)",
    "技能培训",
    "考试准备",
    "信息分析与研究",
    "自我提升"
  ],
  "cached": true
}

错误响应

未找到单词

当请求的单词尚未生成记忆卡片时返回。这可能是因为:

  • 单词是生僻词
  • 单词尚未被收录
  • 拼写错误

404 响应

{
  "success": false,
  "error": "该单词暂未生成记忆卡片",
  "code": "NOT_FOUND",
  "message": "单词 \"xyz\" (en) 尚未生成记忆卡片。",
  "rateLimit": {
    "remaining": 497,
    "limit": 150,
    "reset": "2025-10-24T00:00:00.000Z"
  }
}

超出限额

当 IP 地址的每日请求次数超过限额时返回。限额在每天 UTC 0:00 自动重置。

429 响应

{
  "success": false,
  "error": "请求次数已达今日上限",
  "code": "RATE_LIMIT_EXCEEDED",
  "rateLimit": {
    "remaining": 0,
    "limit": 150,
    "reset": "2025-10-24T00:00:00.000Z"
  }
}

参数错误

当请求参数不符合要求时返回。常见原因:

  • word 参数为空
  • word 长度超过 100 字符
  • 参数类型不正确

400 响应

{
  "success": false,
  "error": "参数错误:word 参数必须是非空字符串",
  "code": "INVALID_PARAMETER",
  "rateLimit": {
    "remaining": 496,
    "limit": 150,
    "reset": "2025-10-24T00:00:00.000Z"
  }
}

服务器错误

服务器内部错误。如果持续遇到此错误,请联系技术支持。

150 响应

{
  "success": false,
  "error": "服务器内部错误",
  "code": "INTERNAL_ERROR"
}

支持的语言

API 支持以下语言的单词查询:

暂时只支持部分英语单词,数据还在慢慢增加

  • Name
    en
    Description
    英语
  • Name
    es
    Description
    西班牙语
  • Name
    ja
    Description
    日语
  • Name
    de
    Description
    德语
  • Name
    fr
    Description
    法语
  • Name
    it
    Description
    意大利语
  • Name
    pt
    Description
    葡萄牙语
  • Name
    ru
    Description
    俄语
  • Name
    ko
    Description
    韩语
  • Name
    ar
    Description
    阿拉伯语

多语言查询

# 英语
curl "https://api.keykey.cc/api/public/memory-card?word=hello&lang=en"

# 西班牙语
curl "https://api.keykey.cc/api/public/memory-card?word=hola&lang=es"

# 日语
curl "https://api.keykey.cc/api/public/memory-card?word=こんにちは&lang=ja"

Was this page helpful?