API

基础地址 https://api.gengwiki.com/v1，返回 JSON。

鉴权

在我的组合新建一个组合，就会得到它的 API Key

curl https://api.gengwiki.com/v1/memes/search?q=躺平 \
  -H "Authorization: Bearer gwk_live_xxx"

不带 Key 也能调用，只能看到全站热门榜的前 20 个梗和最早收录的 10 个人物，没有人设和表情包。/tags 和带 tag 的 /trending 返回空列表，/me 开头的接口返回 401。

范围

创建 Key 时选择它的范围和权限，之后的检索都只在范围内进行，调用没有勾选权限的接口会返回 403

梗

任意多个，/memes 只返回这些

人设

最多一个，选中后会带入它关联的梗和最多 100 张表情

表情包

最多 5 个，合计最多 200 张，/stickers 只返回这些

人物

最多 20 个，/people/linked 只返回这些

全站热门梗走单独的 /trending，全部人物走单独的 /people，都不受范围限制。旧 Key 没有 people:read，也没有关联人物，要用人物请新建一个 Key

私有的人设、表情包和人物只有自己的 Key 能用，不公开，也不用审核。可以用 /me 开头的接口添加，也可以在网站上创建时勾选仅自己使用。每个 Key 都有 self:write，只能改自己的内容

接口

梗

GET /memes/search?q=&limit= memes:read

在 Key 关联的梗里搜索，q 匹配名称、别名和使用场景，为空时按热度列出，每条含简介（summary）和使用场景（usage_scenario）

curl "https://api.gengwiki.com/v1/memes/search" -H "Authorization: Bearer gwk_live_xxx"

GET /memes/{slug} memes:read

Key 关联的梗的详情，含使用场景（usage_scenario）、用法示例（usage_examples）、相关梗、贡献者和最后更改时间

curl "https://api.gengwiki.com/v1/memes/{slug}" -H "Authorization: Bearer gwk_live_xxx"

标签和热门

GET /tags trending:read

全部标签和每个标签的梗数量，用得最多的在前，不受 Key 范围限制

curl "https://api.gengwiki.com/v1/tags" -H "Authorization: Bearer gwk_live_xxx"

人设

GET /persona persona:read

Key 绑定的人设，含完整 System Prompt

curl "https://api.gengwiki.com/v1/persona" -H "Authorization: Bearer gwk_live_xxx"

表情包

GET /stickers/search?q=&limit= stickers:read

在 Key 关联的表情包里按说明、名称、标签搜索

curl "https://api.gengwiki.com/v1/stickers/search" -H "Authorization: Bearer gwk_live_xxx"

GET /sticker-packs stickers:read

Key 关联的表情包及全部图片

curl "https://api.gengwiki.com/v1/sticker-packs" -H "Authorization: Bearer gwk_live_xxx"

GET /stickers/{id}/image 无需 Key

图片本身，可直接放进 Markdown 或 img，按 IP 限流

curl "https://api.gengwiki.com/v1/stickers/{id}/image"

人物

GET /people?q=&limit=&offset= people:read

全站所有人物，不受 Key 范围限制，q 匹配名字、别名、标签、简介和语录，每次最多 100 条，用 offset 翻页

curl "https://api.gengwiki.com/v1/people" -H "Authorization: Bearer gwk_live_xxx"

GET /people/linked people:read

Key 关联的人物，含简介和全部语录

curl "https://api.gengwiki.com/v1/people/linked" -H "Authorization: Bearer gwk_live_xxx"

GET /people/{id 或名字} people:read

特定人物的详情，按 id、准确的名字或别名查找，含提到这个人物的梗（memes）

curl "https://api.gengwiki.com/v1/people/{id 或名字}" -H "Authorization: Bearer gwk_live_xxx"

个人词库

GET /me/lexicons lexicon:read:self

我的个人词库

curl "https://api.gengwiki.com/v1/me/lexicons" -H "Authorization: Bearer gwk_live_xxx"

POST /me/lexicons lexicon:write:self

新建个人词库

curl -X POST "https://api.gengwiki.com/v1/me/lexicons" -H "Authorization: Bearer gwk_live_xxx"

GET /me/lexicons/{id}/entries lexicon:read:self

个人词库词条

curl "https://api.gengwiki.com/v1/me/lexicons/{id}/entries" -H "Authorization: Bearer gwk_live_xxx"

POST /me/lexicons/{id}/entries lexicon:write:self

添加个人词条

curl -X POST "https://api.gengwiki.com/v1/me/lexicons/{id}/entries" -H "Authorization: Bearer gwk_live_xxx"

我自己的内容

POST /me/words self:write

添加一个词到我的第一个个人词库，没有词库时自动新建，body 是 {"term","note"}，同名的词会更新解释

curl -X POST "https://api.gengwiki.com/v1/me/words" -H "Authorization: Bearer gwk_live_xxx"

DELETE /me/words/{term} self:write

从我的全部个人词库删除这个词

curl -X DELETE "https://api.gengwiki.com/v1/me/words/{term}" -H "Authorization: Bearer gwk_live_xxx"

POST /me/stickers?caption= self:write

添加一张表情，body 是图片本身，最大 1MB，边长不超过 500，放进我的私有表情包并关联到这个 Key

curl -X POST "https://api.gengwiki.com/v1/me/stickers" -H "Authorization: Bearer gwk_live_xxx"

DELETE /me/stickers/{caption} self:write

删除说明完全相同的私有表情，删空的表情包也一起删除

curl -X DELETE "https://api.gengwiki.com/v1/me/stickers/{caption}" -H "Authorization: Bearer gwk_live_xxx"

POST /me/personas self:write

添加私有人设，body 是 {"title","prompt","description"}，同名的会更新。Key 的人设不能改，要用它请新建一个组合

curl -X POST "https://api.gengwiki.com/v1/me/personas" -H "Authorization: Bearer gwk_live_xxx"

DELETE /me/personas/{title} self:write

删除私有人设

curl -X DELETE "https://api.gengwiki.com/v1/me/personas/{title}" -H "Authorization: Bearer gwk_live_xxx"

POST /me/people self:write

添加私有人物并关联到这个 Key，body 是 {"name","bio","quotes"}，同名的会更新

curl -X POST "https://api.gengwiki.com/v1/me/people" -H "Authorization: Bearer gwk_live_xxx"

DELETE /me/people/{name} self:write

删除私有人物

curl -X DELETE "https://api.gengwiki.com/v1/me/people/{name}" -H "Authorization: Bearer gwk_live_xxx"

账号

GET /me/usage 无

近 30 天调用量

curl "https://api.gengwiki.com/v1/me/usage" -H "Authorization: Bearer gwk_live_xxx"

GET /me/rate-limit 无

当前限流档位与剩余额度

curl "https://api.gengwiki.com/v1/me/rate-limit" -H "Authorization: Bearer gwk_live_xxx"

服务

GET /health 无需 Key

服务状态，正常时返回 {"status":"ok"}

curl "https://api.gengwiki.com/v1/health"

DeepSeek Function Calling

把下面的工具定义传给模型，模型遇到不认识的梗时会主动调用。

{
  "type": "function",
  "function": {
    "name": "search_memes",
    "description": "搜索中文网络热梗，返回释义和用法。遇到不认识的网络用语时调用。",
    "parameters": {
      "type": "object",
      "properties": {
        "q": { "type": "string", "description": "梗的关键词、别名或拼音缩写" },
        "limit": { "type": "integer", "description": "返回条数，默认 5" }
      },
      "required": ["q"]
    }
  }
}

完整的 Python 调用示例

import json, requests
from openai import OpenAI

client = OpenAI(api_key="sk-...", base_url="https://api.deepseek.com")
GW = {"Authorization": "Bearer gwk_live_xxx"}
tools = [TOOL]  # 上面的 search_memes

def search_memes(q, limit=5):
    r = requests.get("https://api.gengwiki.com/v1/memes/search", params={"q": q, "limit": limit}, headers=GW)
    return r.json()

messages = [{"role": "user", "content": "同事说我身上班味好重，是什么意思？"}]
resp = client.chat.completions.create(model="deepseek-chat", messages=messages, tools=tools)
msg = resp.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    result = search_memes(**json.loads(call.function.arguments))
    messages += [msg, {"role": "tool", "tool_call_id": call.id,
                       "content": json.dumps(result, ensure_ascii=False)}]
    resp = client.chat.completions.create(model="deepseek-chat", messages=messages, tools=tools)

print(resp.choices[0].message.content)

限流

每个 Key 每分钟 600 次，每天 100,000 次

这些维度同时计数，任一超出都会返回 429

维度	每分钟	每天	说明
API Key	600	100,000	同一个 Key 的所有请求合计，不论来自哪台机器
IP	1,200	不限	同一个 IP 的所有请求合计，包括无效 Key 的请求，用来拦截刷接口和猜 Key
图片	300	2,000	/stickers/{id}/image 按 IP 单独计数，不占 Key 的额度
无 Key	60	5,000	不带 Key 的请求按 IP 合计

分钟按自然分钟计算，每天在 UTC 零点（北京时间 8 点）重置
429 响应带 Retry-After，等这么多秒后再重试
用 /me/rate-limit 随时查看这个 Key 的用量

表情图片

搜索和列表接口只返回图片链接，图片要单独请求
图片内容不会变化，响应带一年的缓存头，请缓存后再展示，不要重复下载
全站每天有图片流量上限，用完后所有图片返回 429，直到 UTC 零点
支持 PNG、JPEG、GIF 和 WebP，动图也一样，每张不超过 1 MB，长宽不超过 500 像素
每个表情包最多 30 张，每个人设关联的表情合计最多 100 张，每个 Key 最多关联 5 个表情包，合计最多 200 张

错误码

{ "error": { "code": "forbidden", "message": "..." } }

400	bad_request	参数不合法
401	unauthorized	无效的 API Key，或不带 Key 调用 /me 开头的接口
403	forbidden	缺少 scope
404	not_found	资源不存在，或不在此 Key 的范围内
429	rate_limited	超出限流，按 Retry-After 秒数后重试

继续看 AstrBot 插件

不用写代码，让机器人玩梗、发表情包、切换人设

大肥鱼开发交流群

鉴权

范围

接口

梗

标签和热门

人设

表情包

人物

个人词库

我自己的内容

账号

服务

DeepSeek Function Calling

限流

表情图片

错误码