Glymonir HTTP API

以编程方式访问 Glymonir 图库 —— 浏览 / 搜索 / 下载公开图库、管理自己的库、上传图片。 官方 glymonir-cli 是它的封装,也可直接用 HTTP 调用。

Base URL  https://api.glymonir.com/api  ·  本地开发:http://localhost:8123/api

快速上手(CLI)

npm i -g glymonir-cli                       # 或给任意命令加前缀:npx glymonir-cli …
glymonir login --api-key gly_live_xxxxxxxx  # 存一次 key

glymonir gallery search cat --limit 5                                   # 预览匹配
glymonir gallery download cat --variant original --meta --out ./out     # 下图片 + 元数据
glymonir upload ./*.jpg --library "Travel 2026"                         # 上传到自己的库

在网站后台(设置 → API 密钥)创建 key,login 一次,之后所有命令复用。

认证

把 API key 作为 Bearer token 发送:

Authorization: Bearer gly_live_xxxxxxxx

key 代理创建它的用户身份。在后台(设置 → API 密钥)创建 / 撤销 key,或用 密钥管理端点。

Scope

一把 key 带三个 scope 中的一个或多个 —— 按需最小授予:

Scope	允许
read	读 / 搜 / 下载公开图库 + 自己的库和合集
write	上传到自己的库,并管理它们(创建 / 编辑 / 整理)
delete	删自己的图片 / 合集 (预留 —— 暂未接端点)

公开图库通过 API 只读 —— 浏览、搜索、下载;你的上传一律进自己的库(见下)。 作用域之外,套餐决定数据深度:图片元数据里的多语言 caption / concepts 需要 Pro 订阅。

限速

按 API key,取决于持有人的套餐。图片字节(走 CDN)不计费,只计 API 调用。

档位	每分钟(突发)	每月
Free / Starter	60(120）	50,000
Pro	300(600）	500,000

超限 → 42900,带 Retry-After 头。CLI 会自动匀速。

响应封装

每个响应都是同一形状:

{ "code": 0, "data": { /* … */ }, "message": "ok" }

code: 0 = 成功;任何非零 code 都是错误(见下表)。HTTP 状态码对应类别(200 / 4xx / 5xx),但始终以 code 为准。

错误码

code	含义
0	OK
40000	请求 / 参数非法
40100	未登录(key 缺失 / 错误 / 过期)
40101	key 缺少该端点所需的 scope
40300	禁止(用户级权限检查未过)
40400	未找到(或不在公开图库 / 不属于你)
42500	向量还没算出来 —— 几分钟后重试
42900	触发限速(带 Retry-After)
50000	服务端错误

---

CLI 命令

npm i -g glymonir-cli 安装(或给命令加 npx 前缀)。认证按顺序解析:--api-key flag → GLYMONIR_API_KEY 环境变量 → login 存的。完整 flag 看 glymonir <命令> --help。

login / logout

glymonir login --api-key gly_live_… [--api-base https://api.glymonir.com/api]
glymonir logout

gallery search [关键词]

预览匹配(总数 + 前几行),不下载。

glymonir gallery search cat --ratio landscape --limit 5
glymonir gallery search --color "#3a4f6b"

过滤:--ratio <landscape|portrait|square|panoramic|tall | 16:9 | 1.78>、 --color <hex>、--limit <n≤50>。需要 read。

gallery download [关键词]

同样的过滤,然后把图片字节下到 --out。

选项	含义
--variant <original|preview|thumbnail|all>	下哪种尺寸 —— 默认 original
--meta	同时写 <上传者>-<code>.json 元数据 sidecar
--limit <n> · --resume · --concurrency <n>	限张数 · 跳过磁盘已有 · 并发下载数

需要 read。下载会给图片的浏览量 + 下载量 +1。

library / collection

glymonir library list
glymonir library create "Travel 2026"
glymonir library download "Travel 2026" --variant thumbnail --out ./lib

glymonir collection create "Travel 2026" "Japan"
glymonir collection download "Travel 2026" "Japan" --out ./japan

<library> 和 <collection> 接受名字或 id(名字用户内 / 库内唯一)。list / download 需要 read,create 需要 write。永远仅自己。

upload [文件…]

glymonir upload ./*.jpg --library "Travel 2026"      # 按名字传到某个库
glymonir upload ./photos/*.jpg --library 42 --resume # 断点续传到 42 号库

本地预处理(各尺寸、palette、thumbhash)后上传到自己的库 —— 传 --library <名字|id> (需要 write)。其它 flag: --name、--introduction、--tags、--manifest <jsonl>、--resume、 --concurrency、--dry-run。--manifest 一行一个 JSON 对象 ({"file":"…","name":"…","tags":[…],"libraryId":"…"})做逐文件元数据。 name 是可选字段:不传 --name 且 manifest 也没有 name 时,CLI 不会从文件名 生成名称,API 会保存 picture.name = null。

---

HTTP API

每个端点都带 Authorization: Bearer <key>,返回上面的封装。图片用短 base58 code 寻址(从不用内部 id)。

图库读取(read)

只返回公开图库、过审的图。其它(不存在 / 属于私有库 / 未过审)一律折叠成 40400。

端点	用途	关键参数
GET /gallery/pictures	浏览,时间倒序(游标)	cursor、limit(≤200)
GET /gallery/search	关键词 + 过滤搜索,带 total	q、color(hex)、minRatio / maxRatio、page / size
GET /gallery/picture/{code}	单图完整元数据	—
POST /gallery/downloads	上报下载(浏览 + 下载 +1)	body { "codes": ["…"] }

浏览 / 搜索返回「lite」item(code、name、尺寸、ratio、urls…)。详情端点额外给 caption / concepts(仅 Pro 账号才填,否则为空):

{
  "tier": "pro", "code": "upWAGbVRyd", "uploader": "alice",
  "width": 4032, "height": 3024, "ratio": 1.333,
  "format": "JPEG", "sizeBytes": "5242880",
  "urls": { "original": "…", "preview": "…", "thumbnail": "…" },
  "canonicalUrl": "…", "attribution": { "text": "…", "url": "…" },
  "thumbhash": "…", "palette": [ … ], "exif": { … },
  "name": "…", "introduction": "…", "tags": [ … ],
  "caption":  { "en": "…", "zh-cn": "…", "ja-jp": "…", "ko-kr": "…" },
  "concepts": { "en": [ … ], "zh-cn": [ … ], "ja-jp": [ … ], "ko-kr": [ … ] }
}

你自己的库(/me —— 仅限自己)

端点	用途
GET /me/libraries · POST /me/libraries	列 / 建你的库(POST body { "name": "…" })
GET /me/libraries/{id}/collections · POST …/collections	列 / 建合集
GET /me/libraries/{id}/pictures	搜你的库(图库过滤 + since / until)
GET /me/collections/{id}/pictures	列合集(page / size)

读需要 read,建需要 write。每个端点都仅限自己 —— 别人的库返回 40400。

图片上传(write)

最简路径:upload CLI 命令。所有上传的限制:仅 JPEG / PNG / WebP、 ≤ 50 MB。违反返回 40000 并指明规则。

裸 HTTP(非 Node 集成方)是两段式:POST /picture/upload/r2/check(去重探测 → 给你还没有的 变体返回 presigned PUT URL)→ PUT 字节到这些 URL → POST /picture/upload/r2/finalize (建行)。finalize body 中的 name、introduction、tags 都是可选字段;省略 name（或发送 JSON null）会创建无显示名称的图片,API 不会用文件名或哈希兜底。 生成各变体的参考实现见 CLI 的 preprocess.ts。

API 密钥管理

在后台(设置 → API 密钥)管理 key,或用 /user/api-keys 编程管理:

端点	用途
POST /user/api-keys	创建 —— body { "name": "…", "scopes": ["read"], "description"?, "expiresInDays"? };响应仅一次带明文 key
GET /user/api-keys	列你的 key(无明文)
POST /user/api-keys/{id}/revoke	撤销 key
GET /user/api-keys/available-scopes	你能授予的 scope

key 发出后 scope 不可变 —— 要改就建新 key、撤旧 key。密钥管理用你的后台登录态,不用 API key。