{
 "openapi": "3.1.0",
 "info": {
  "title": "感觉检索 API",
  "version": "0.3.0",
  "description": "两层结构：感受词 → 视觉风格。762 个词、598 个风格。 v1 已下线（感受层撤除），返回 410 Gone。 POST /v2/analyze 每次 $0.10；没额度时返 402，同时声明 x402（USDC / Base + Solana）与支付宝 AI 付（CNY）两条轨道。 机器可读定价见 https://xiximm.cloud/.well-known/x402，给 AI 的说明见 https://xiximm.cloud/llms.txt。",
  "x-pricing": {
   "model": "per-call",
   "usd": 0.1,
   "rails": [
    "x402",
    "alipay"
   ],
   "discovery": "https://xiximm.cloud/.well-known/x402"
  }
 },
 "externalDocs": {
  "url": "https://xiximm.cloud/llms.txt",
  "description": "AI 友好说明（语义、数据结构、计费与 402 流程）"
 },
 "servers": [
  {
   "url": "https://xiximm.cloud"
  }
 ],
 "paths": {
  "/v2/analyze": {
   "post": {
    "summary": "一句话 → 感受词 + 视觉风格（不含图）",
    "description": "默认只返回词与风格 id/定义，**不返回图片**。要图请再调 /v2/images（一次最多 5 个，计 1 次额度） 或 /v2/styles/{id}（计 1 次额度）。本接口本身也计 1 次额度。",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "text"
        ],
        "properties": {
         "text": {
          "type": "string",
          "maxLength": 500,
          "description": "中文或英文的口语描述"
         },
         "words": {
          "type": "integer",
          "minimum": 1,
          "maximum": 12,
          "default": 8
         },
         "styles": {
          "type": "integer",
          "minimum": 1,
          "maximum": 30,
          "default": 12
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "解析结果",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Analyze"
        }
       }
      }
     },
     "400": {
      "description": "text 为空或 JSON 不合法"
     },
     "402": {
      "description": "需要支付。两条轨道可能同时声明：x402（PAYMENT-REQUIRED 头，英文站/海外 Agent） 与支付宝 AI 付（Payment-Needed 或 amtPaymentLink 头）。买到额度后带 X-FS-Quota 调用即只扣次。",
      "headers": {
       "PAYMENT-REQUIRED": {
        "description": "base64(PaymentRequired)，x402 v2；body 里另有 x402Version/resource/accepts",
        "schema": {
         "type": "string"
        }
       },
       "Payment-Needed": {
        "description": "base64url(商家自签账单)，支付宝 AI 付",
        "schema": {
         "type": "string"
        }
       },
       "amtPaymentLink": {
        "description": "支付宝官方预下单返回的 amt_pre_pay_id",
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "410": {
      "description": "v1 已下线（仅 /v1/*）"
     },
     "413": {
      "description": "text 超过字数上限"
     },
     "429": {
      "description": "限流"
     }
    }
   }
  },
  "/v2/dictionary": {
   "get": {
    "summary": "枚举全部词与风格",
    "responses": {
     "200": {
      "description": "词表 + 风格表",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Dictionary"
        }
       }
      }
     }
    }
   }
  },
  "/v2/links": {
   "get": {
    "summary": "词 ↔ 风格 关联查询（免费，只限流）",
    "description": "不扣额度、不返回图片。?word=<感受词> 给「这个词落到哪些风格」（附带 gloss/反义词/共现词）；?style=<风格 id> 给「这个风格有哪些感受词」（标识词在前）。 这是词↔风格的正式接口（查询串形式，任何托管都能路由）。",
    "parameters": [
     {
      "name": "word",
      "in": "query",
      "required": false,
      "description": "感受词，如 霓虹",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "style",
      "in": "query",
      "required": false,
      "description": "风格 id，如 synthwave",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "关联结果（二选一）",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/WordLinks"
          },
          {
           "$ref": "#/components/schemas/StyleWords"
          }
         ]
        }
       }
      }
     },
     "400": {
      "description": "word 与 style 都没给"
     },
     "404": {
      "description": "词或风格不存在"
     },
     "429": {
      "description": "限流"
     }
    }
   }
  },
  "/v2/images": {
   "get": {
    "summary": "批量取风格对应的图（计 1 次额度，最多 5 个）",
    "description": "一次请求取多个风格的图，比逐个 /v2/styles/{id} 省额度。GET 用 ?ids=a,b,c，POST 用 body {\"ids\":[...]}。 上限 5 个：960px 大图一张约 170KB，一次给太多等于 0.01 元卖几十 MB 流量。",
    "parameters": [
     {
      "name": "ids",
      "in": "query",
      "required": false,
      "description": "逗号分隔的风格 id，1–5 个（POST 时改用 body）",
      "schema": {
       "type": "string",
       "example": "synthwave,cyberpunk"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "图列表",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "count": {
           "type": "integer"
          },
          "images": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "image": {
              "$ref": "#/components/schemas/Image"
             }
            }
           }
          },
          "missing": {
           "type": "array",
           "items": {
            "type": "string"
           },
           "description": "不存在或没有图的 id"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "缺少 ids 或 id 非法"
     },
     "402": {
      "description": "没有额度（计费开启时）"
     },
     "413": {
      "description": "一次超过 5 个 id"
     },
     "429": {
      "description": "限流"
     }
    }
   },
   "post": {
    "summary": "批量取图（POST 形式）",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "ids"
        ],
        "properties": {
         "ids": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "minItems": 1,
          "maxItems": 5
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "同 GET"
     },
     "402": {
      "description": "没有额度"
     }
    }
   }
  },
  "/v2/styles/{id}": {
   "get": {
    "summary": "按 id 取单个风格（含对应图片，计 1 次额度）",
    "description": "计 1 次额度。要一次拿多张图请用 /v2/images（同样 1 次额度）。也支持查询串形式 /v2/styles?id=<id>。",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "maxLength": 64
      },
      "example": "synthwave"
     }
    ],
    "responses": {
     "200": {
      "description": "风格详情",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "style": {
           "$ref": "#/components/schemas/StyleDetail"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "缺少 id"
     },
     "402": {
      "description": "没有额度（计费开启时）"
     },
     "404": {
      "description": "未知风格 id"
     },
     "429": {
      "description": "限流"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Word": {
    "type": "object",
    "properties": {
     "w": {
      "type": "string"
     },
     "score": {
      "type": "number"
     },
     "share": {
      "type": "integer",
      "description": "被几个风格使用；≤3 为标识词"
     },
     "styles": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "StyleHit": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "en": {
      "type": [
       "string",
       "null"
      ]
     },
     "score": {
      "type": "number"
     },
     "hits": {
      "type": "integer"
     },
     "matched": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "命中的词，可直接引用"
     },
     "def": {
      "type": [
       "string",
       "null"
      ]
     },
     "parent": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "Image": {
    "type": "object",
    "description": "风格对应的图。thumb/full 是按请求 origin 拼好的绝对地址；kind 说明图的性质。",
    "properties": {
     "ref": {
      "type": "string",
      "description": "图在 media/manifest.json 里的键"
     },
     "thumb": {
      "type": [
       "string",
       "null"
      ],
      "description": "320px WebP"
     },
     "full": {
      "type": [
       "string",
       "null"
      ],
      "description": "960px WebP"
     },
     "w": {
      "type": [
       "integer",
       "null"
      ]
     },
     "h": {
      "type": [
       "integer",
       "null"
      ]
     },
     "palette": {
      "type": [
       "array",
       "null"
      ],
      "items": {
       "type": "string"
      },
      "description": "三个主色，由亮到暗"
     },
     "kind": {
      "type": "string",
      "enum": [
       "work",
       "synthetic",
       "placeholder"
      ],
      "description": "work=有出处的真作品；synthetic=AI 生成示意；placeholder=样张未完成的占位图"
     },
     "credit": {
      "type": "string",
      "description": "出处/生成方式，可直接展示"
     },
     "license": {
      "type": "string",
      "description": "CC0 / AI-generated / placeholder"
     },
     "source": {
      "type": "string"
     },
     "source_url": {
      "type": "string"
     }
    }
   },
   "StyleDetail": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "en": {
      "type": [
       "string",
       "null"
      ]
     },
     "name_status": {
      "type": [
       "string",
       "null"
      ]
     },
     "def": {
      "type": [
       "string",
       "null"
      ],
      "description": "一句话定义"
     },
     "defGen": {
      "type": [
       "string",
       "null"
      ],
      "description": "生成用提示词段落"
     },
     "terms": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "origins": {
      "type": [
       "object",
       "null"
      ],
      "description": "年代 / 地域 / 媒介"
     },
     "parent": {
      "type": [
       "string",
       "null"
      ]
     },
     "variant": {
      "type": [
       "string",
       "null"
      ]
     },
     "chain": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "conf": {
      "type": [
       "string",
       "null"
      ],
      "description": "与近邻风格的差别"
     },
     "images": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Image"
      }
     }
    }
   },
   "Analyze": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "input": {
      "type": "object",
      "properties": {
       "text": {
        "type": "string"
       },
       "lang": {
        "type": "string"
       },
       "chars": {
        "type": "integer"
       }
      }
     },
     "words": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Word"
      }
     },
     "styles": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/StyleHit"
      }
     },
     "excluded": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "meta": {
      "type": "object",
      "properties": {
       "version": {
        "type": "string"
       },
       "engine": {
        "type": "string"
       },
       "matched_words": {
        "type": "integer"
       },
       "latency_ms": {
        "type": "number"
       }
      }
     }
    }
   },
   "WordLinks": {
    "type": "object",
    "description": "一个感受词，及它落到的风格。免费接口，不含图片。",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "word": {
      "type": "string"
     },
     "share": {
      "type": "integer",
      "description": "被几个风格共用；≤6 记为标识词"
     },
     "marker": {
      "type": "boolean",
      "description": "true = 标识词（更能区分风格）"
     },
     "gloss": {
      "type": [
       "string",
       "null"
      ],
      "description": "词袋式的近义词串"
     },
     "explain": {
      "type": [
       "string",
       "null"
      ],
      "description": "一句属性描述"
     },
     "english": {
      "type": [
       "string",
       "null"
      ]
     },
     "styles": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "id": {
         "type": "string"
        },
        "name": {
         "type": [
          "string",
          "null"
         ]
        },
        "en": {
         "type": [
          "string",
          "null"
         ]
        },
        "def": {
         "type": [
          "string",
          "null"
         ]
        }
       }
      }
     },
     "opposite": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "co_occurs": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "同一风格里常一起出现的词"
     }
    }
   },
   "StyleWords": {
    "type": "object",
    "description": "一个风格，及它的感受词（按 share 升序：标识词在前）。免费接口，不含图片。",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "style": {
      "type": "object",
      "properties": {
       "id": {
        "type": "string"
       },
       "name": {
        "type": "string"
       },
       "en": {
        "type": [
         "string",
         "null"
        ]
       },
       "def": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "count": {
      "type": "integer"
     },
     "words": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "w": {
         "type": "string"
        },
        "share": {
         "type": "integer"
        },
        "marker": {
         "type": "boolean"
        }
       }
      }
     }
    }
   },
   "Dictionary": {
    "type": "object",
    "properties": {
     "ok": {
      "type": "boolean"
     },
     "words": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "styles": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "counts": {
      "type": "object",
      "properties": {
       "words": {
        "type": "integer"
       },
       "styles": {
        "type": "integer"
       }
      }
     }
    }
   }
  }
 }
}