感觉检索 API

v0.3 · 两层结构：感受词（762）→ 视觉风格（598，含 181 个变种）。v1 已下线（感受层撤除），返回 410 Gone。

结构变了：没有 feelings[]、没有 7 维画像、没有作品实体。查询落在一组词上，再把词落到风格上；styles[].matched 是命中的词，可以直接引用给用户看。

POST /v2/analyze

curl -s https://xiximm.cloud/v2/analyze \
  -H 'Content-Type: application/json' \
  -d '{"text":"留白很多，几何克制，低饱和","words":5,"styles":4}'

{
  "ok": true,
  "input": { "text": "…", "lang": "zh", "chars": 14 },
  "words": [
    { "w": "克制", "score": 1, "share": 1, "styles": ["minimalism"] }
  ],
  "styles": [
    { "id": "minimalism", "name": "极简主义", "score": 0.87,
      "hits": 3, "matched": ["留白","克制","几何"], "def": "最少元素、留白、几何秩序。" }
  ],
  "excluded": [],
  "meta": { "version": "0.3.0", "engine": "lexicon", "matched_words": 5, "latency_ms": 0.8 }
}

字段	说明
`text`	必填，中文或英文口语描述，≤500 字
`words`	返回几个词，1–12，默认 8
`styles`	返回几个风格，1–30，默认 12

GET /v2/dictionary

一次拉全量词表与风格表（各自带定义、词集、共享度），适合先做参数校验或本地建索引。

{ "ok": true, "words": [...], "styles": [...], "counts": { "words": 762, "styles": 598 } }

词 ↔ 风格互查（免费，只限流）

不扣额度、不返回图片，随便查。两个方向都走同一个端点（查询串形式，任何托管都能路由）：

# 这个词落到哪些风格
curl -s 'https://xiximm.cloud/v2/links?word=%E9%9C%93%E8%99%B9'   # 霓虹
{
  "ok": true, "word": "霓虹", "share": 12, "marker": false,
  "gloss": "霓虹、灯管、发光字、招牌、电光、色管",
  "explain": "…", "english": "neon",
  "styles": [
    { "id": "cyberpunk", "name": "赛博朋克", "en": "Cyberpunk", "def": "…" },
    { "id": "oriental-cyberpunk", "name": "东方赛博", … }
  ],
  "opposite": [], "co_occurs": ["夜", "反光", …]
}

# 这个风格有哪些感受词（标识词在前，share 越小越能区分它）
curl -s 'https://xiximm.cloud/v2/links?style=synthwave'
{
  "ok": true,
  "style": { "id": "synthwave", "name": "合成器波", "en": "Synthwave", "def": "…" },
  "count": 11,
  "words": [
    { "w": "网格地平", "share": 6, "marker": true },
    { "w": "宇宙感",   "share": 8, "marker": false }
  ]
}

自建部署若支持嵌套动态路由，也可以用 /v2/words/{词} 与 /v2/styles/{id}/words （handler 里已实现；EdgeOne 的函数路由不支持这种嵌套，线上以 /v2/links 为准）。

share = 这个词被几个风格共用；≤6 记为 marker（标识词），挑风格时优先看标识词，share 大的多是泛词（留白、几何）。

取风格对应的图（单独计 1 次额度）

分析默认不给图——/v2/analyze 只返回词与风格。image 字段只在下面两个取图接口里出现，每次请求扣 1 次额度（和一次分析同价），一次最多 5 个风格（960px 大图一张约 170KB，给多了等于 0.01 元卖几十 MB 流量）：

curl -s 'https://xiximm.cloud/v2/images?ids=synthwave,cyberpunk,pop' -H 'X-FS-Quota: <token>'

{
  "ok": true, "count": 3,
  "images": [
    { "id": "synthwave", "name": "合成器波",
      "image": { "thumb": "https://xiximm.cloud/media/works/g_synthwave@320.….webp",
                 "full":  "https://xiximm.cloud/media/works/g_synthwave@960.….webp",
                 "w": 960, "h": 960, "kind": "synthetic",
                 "credit": "AI 生成 · 模仿合成器波风格（沿用游点灵样张「霓虹跑车落日」）",
                 "license": "AI-generated", "source_url": "…" } }
  ],
  "missing": ["no-such-id"]
}

只要一个风格的定义 + 图时用 GET /v2/styles/{id}（同样 1 次额度）。kind 说明图的性质：

kind	含义
`work`	有出处的真作品（`license: CC0`），可直接引用
`synthetic`	AI 生成示意（`license: AI-generated`），模仿风格本身、不指向任何具体作品
`placeholder`	样张还没做完的占位图，不要当样本用

只想拿某一个风格的图和定义时，用单风格接口（只限流、不计次）：

curl -s https://xiximm.cloud/v2/styles/synthwave

{
  "ok": true,
  "style": {
    "id": "synthwave", "name": "合成器波", "def": "…", "defGen": "…",
    "terms": ["霓虹", "网格", "紫粉", "…"], "origins": { "period": "1980s", "region": "美国" },
    "images": [ { "thumb": "…", "full": "…", "kind": "synthetic", "credit": "…", "license": "AI-generated" } ]
  }
}

怎么读返回结果

信号	含义
`matched`	这个风格命中了哪几个词。比 score 更适合展示（「命中留白·克制·几何 3/4」）
`share`	这个词被几个风格使用。≤3 是标识词（锋利、可区分），数值大是泛词
`score`	命中权重 ÷ √词集规模 ÷ √查询范数。相对值，不是概率，跨查询不可比
`excluded`	被否定掉的词（「不要热闹」）

离线 / 自建

不想调接口就拿静态文件：latest.json（结构 + 词索引）、 words.json（词条全文）、styles.json（风格详情）、 aliases.json（词面别名）、openapi.json（契约）。

付费：两条 402 轨道

价格：每次 $0.10（美元）。没额度时返回 402，同时声明两条轨道，Agent 按自己的钱包能力挑一条：

x402（USDC，英文站 / 海外 Agent）：读 PAYMENT-REQUIRED 头（base64 的 x402 v2 声明），用钱包签一笔 exact + EIP-3009 授权，重放请求时带 PAYMENT-SIGNATURE。 gas 由 facilitator 代付，不需要注册账号。结算成功后回 PAYMENT-RESPONSE 与 X-FS-Quota。客户端可用 @x402/fetch 一行包住 fetch。
支付宝 AI 付（人民币，国内 Agent）：读 Payment-Needed（商家自签账单）或 amtPaymentLink（官方预下单）。

机器可读的定价与收款地址：/.well-known/x402（x402 发现文件）。

买到额度后，后续请求带 X-FS-Quota: <token> 只扣次、不再碰支付网关， X-FS-Quota-Left 给剩余次数。只想收某一条轨道：请求带 X-FS-Rail: x402|alipay。设计细节与上线清单见 docs/X402-英文站计费.md。

限流与边界

按 IP 限流（20 次/分，计数在实例内存里：Serverless 多实例时实际约为 20 × 并发实例数/分，不是全局硬限；要硬限请用平台侧限流/防护策略）。/v2/analyze 可挂计费闸门（402 协议 + X-FS-Quota 额度头）， /v2/dictionary 与 /v2/styles/:id 只限流不计次。不做服务端推理，语义引擎跑在用户浏览器里。接口只做词典层解析，所以遇到词表外的说法会返回空 words —— 这是预期行为，不是错误。

← 回到检索