表情包 API.

先看这三条

BASE="https://nailong.fall-star.top/api"

# 搜索并保存一张图
curl "$BASE/search?q=开心" -o meme.jpg

# 看图库第一页的元数据
curl "$BASE/gallery?limit=12"

# 下载 ID 4 的原图
curl -OJ "$BASE/images/4?download=1"

01 · 搜索图片

按关键词搜索并直接返回匹配的图片。支持中文、中文同音错字（例如 开新 → 开心）和基础模糊匹配；没有达到阈值时返回一张随机图片。

查询参数

返回

200，响应体为 JPG 或 GIF；Content-Type 为 image/jpeg 或 image/gif。不返回 JSON。

curl "https://nailong.fall-star.top/api/search?q=开心" -o happy.jpg
file happy.jpg       # JPEG image data
curl -I "https://nailong.fall-star.top/api/search?q=开心"

02 · 搜索元数据

和 /api/search 使用同样的搜索参数，但返回图片信息、匹配方式和回退状态。适合详情页、搜索结果卡片和“没有精确匹配”提示。

curl "https://nailong.fall-star.top/api/search/meta?q=开新"

{
  "id": "4",
  "name": "乖巧待机",
  "tag": ["奶蛙", "开心"],
  "image_url": "https://nailong.fall-star.top/api/images/4",
  "image_download_url": "https://nailong.fall-star.top/api/images/4?download=1",
  "width": 134,
  "height": 132,
  "format": "jpeg",
  "source_format": "png",
  "query": "开新",
  "matched_field": "tag",
  "matched_value": "开心",
  "canonical": "happy",
  "score": 0.93,
  "method": "pinyin_tag",
  "fallback": false,
  "candidate_count": 156
}

method 表示命中方式：exact_tag、name_exact、alias_tag、pinyin_tag、fuzzy_tag 或 fallback。当 fallback: true 时，返回的是随机推荐图。

03 · 多结果搜索

返回所有达到阈值的匹配，按相关度排序。它不会在没有结果时偷偷塞一张随机图；前端可以自行显示空状态和“随机一张”按钮。

curl "https://nailong.fall-star.top/api/search/list?q=开心&limit=5"

{
  "query": "开心",
  "total": 158,
  "limit": 5,
  "offset": 0,
  "fallback": false,
  "fallback_reason": null,
  "items": [
    {
      "id": "4",
      "name": "乖巧待机",
      "tag": ["奶蛙", "开心"],
      "score": 1.0,
      "method": "exact_tag",
      "thumb_320_url": "https://nailong.fall-star.top/api/thumbs/4/320"
    }
  ]
}

04 · 随机图片

从公开图库中返回一张随机图片。支持 seed，适合“换一张”或测试可复现结果。

curl "https://nailong.fall-star.top/api/random" -o random.jpg

curl "https://nailong.fall-star.top/api/random/meta?seed=7"

别名：/api/random/image。随机响应使用 Cache-Control: no-store。

05 · 图库与缩略图

图库列表接口，适合图片墙、标签页和分页加载。每条记录包含格式、尺寸、原图地址、下载地址和两档缩略图。

curl "https://nailong.fall-star.top/api/gallery?tag=奶蛙&limit=2"

{
  "total": 361,
  "limit": 2,
  "offset": 0,
  "items": [
    {
      "id": "3",
      "name": "舞会现场",
      "tag": ["奶蛙", "面无表情"],
      "format": "gif",
      "width": 240,
      "height": 240,
      "image_url": "https://nailong.fall-star.top/api/images/3",
      "thumb_url": "https://nailong.fall-star.top/api/thumbs/3/640",
      "thumb_320_url": "https://nailong.fall-star.top/api/thumbs/3/320"
    }
  ]
}

缩略图

GET /api/thumbs/:id/320 或 /640，返回 WebP，适合 <img srcset>。GIF 缩略图使用第一帧；原 GIF 仍走原图接口。

curl "https://nailong.fall-star.top/api/thumbs/4/320" -o 4.webp

单张图库信息：GET /api/gallery/:id，不存在或已被审查过滤时返回 404。

06 · 原图与下载

按 ID 返回原图。默认内联展示；加 ?download=1 时返回附件。

# 浏览器展示
curl "https://nailong.fall-star.top/api/images/4" -o 4.jpg

# 下载
curl -OJ "https://nailong.fall-star.top/api/images/4?download=1"

成功响应包含 ETag、Last-Modified、Accept-Ranges，并支持长缓存。未知或待审查 ID 返回 404。

07 · 索引

完整索引包含 1171 条记录，公开索引包含 1164 条；两者都只含 id、name、tag。

# 完整索引，附件下载
curl -OJ "https://nailong.fall-star.top/api/memes.json"

# 公开索引（过滤 7 条待审查内容）
curl "https://nailong.fall-star.top/api/memes.public.json"

08 · 健康检查

curl "https://nailong.fall-star.top/api/health"

{
  "status": "ok",
  "version": "1.4.0",
  "catalog_entries": 1171,
  "images": 1171,
  "public_images": 1164,
  "hidden_images": 7,
  "review_status": "pending_user_review",
  "memes_count": 1171,
  "search_ready": true
}

通用规则

需要机器可读定义？使用 OpenAPI 3.1 YAML 或 JSON；需要交互调试？打开 Swagger UI。