MemeZ Developer API

把 MemeZ 接入你的产品

用自己的 API Key 查询模板、校验输入，并在机器人、网站或内部工具中直接生成表情包。

登录并创建 Key API 测试

鉴权方式

Authorization: Bearer mz_live_你的_API_Key API Key 仅在创建时完整显示一次，请保存到服务端的密钥管理系统。

Quick start

三步接入

01
创建 API Key
回到首页，使用 QQ 登录后在“账号中心”创建 API Key。完整 Key 只显示一次。
02
查询模板与参数
先请求模板列表获取固定编号，再通过模板详情获取它需要的图片、文字和可选参数。
03
提交生成请求
可上传图片、填写 QQ 号或提供远程图片 URL；接口直接返回生成后的图片二进制。

API reference

接口说明

统一鉴权

所有 /v1/ 接口都必须携带 Bearer API Key。

Authorization: Bearer mz_live_你的_API_Key

不要把 Key 写进网页前端、公开仓库或客户端应用；请由你的服务端发起调用。

模板列表

GET /v1/templates

返回可用模板的固定 id、key、中文名称、关键词和标签。id 从 1 开始永久固定，新增模板只会追加新编号。

curl "https://memez.icu/v1/templates" \
  -H "Authorization: Bearer mz_live_你的_API_Key"

模板详情

GET /v1/memes/{id_or_key}/info

可使用固定编号或英文 key。生成前请读取 params_type，其中包含图片和文字的最小、最大数量，以及 args 的结构。

curl "https://memez.icu/v1/memes/13/info" \
  -H "Authorization: Bearer mz_live_你的_API_Key"

生成表情包

POST /v1/memes/{id_or_key}/，响应体就是图片二进制；可使用固定编号或英文 key。以下示例用编号 13 将结果保存为 meme.png。

curl -X POST "https://memez.icu/v1/memes/13/" \
  -H "Authorization: Bearer mz_live_你的_API_Key" \
  -F "images=@face.png" \
  -F "texts=给你看个傻子" \
  -F 'args={}' \
  --output meme.png

使用 QQ 头像

仍使用统一入口 POST /v1/memes/{id_or_key}/。单图使用 qq；双图使用 qq1、qq2，固定按 1、2 顺序填充。

curl -X POST "https://memez.icu/v1/memes/13/?qq=123456" \
  -H "Authorization: Bearer mz_live_你的_API_Key" \
  -F 'args={}' \
  --output meme.png

# 双图：?qq1=123456&qq2=654321

使用远程图片 URL

仍使用统一入口 POST /v1/memes/{id_or_key}/。单图使用 url；双图使用 url1、url2，固定按 1、2 顺序填充；仅接受公网 HTTPS 图片地址。

curl -X POST "https://memez.icu/v1/memes/13/?url=https%3A%2F%2Fexample.com%2Fface.png" \
  -H "Authorization: Bearer mz_live_你的_API_Key" \
  -F 'args={}' \
  --output meme.png

# 双图：?url1=https%3A%2F%2Fexample.com%2Fa.png&url2=https%3A%2F%2Fexample.com%2Fb.png

生成请求字段

字段	类型	说明
`images`	文件，可重复	按模板详情要求上传 0 至多张图片，顺序即图片使用顺序。
`qq`	查询参数	单图：`qq`。双图：`qq1`、`qq2` 必须同时填写，顺序固定为 1、2。
`url`	查询参数	单图：`url`。双图：`url1`、`url2` 必须同时填写，顺序固定为 1、2；仅接受公网 HTTPS 地址。
`texts`	字符串，可重复	按模板详情要求传入 0 至多行文字，顺序即文字使用顺序。
`args`	JSON 字符串	模板没有附加参数时传 `{}`；有参数时以详情接口返回的结构为准。

远程 URL 会校验 HTTPS、域名解析结果、文件大小、图片格式与像素限制，不支持内网地址、账号认证、非标准端口或重定向。请仅使用你有权处理的 QQ 头像和图片。

Limits & errors

限额、错误与排查

默认限额

每个 API Key 每分钟最多 30 次调用，每天最多 100 次生成调用。生成调用无论成功或失败均会计入当天额度。

常见响应

401：缺少、无效或已停用的 API Key。
422：模板不存在，或图片、文字、参数不符合模板要求。
429：调用频率或每日生成额度已达到限制。
503：生成队列繁忙，请进行退避重试。

接入建议

生成前始终查询模板详情；收到 429 或 503 时使用指数退避重试；不要在日志中记录完整 API Key。