跳到主要内容

更多

语言与货币

Qualit.ly API

来自 Weidian、Taobao 和 1688 的商品数据、QC 图片和元数据。Bearer 令牌认证、宽松的速率限制、分级套餐。

获取 API 密钥快速开始

入门

所有请求都发送到 https://backend.qualit.ly/api/v1。三个步骤：

  1. 1

    获取密钥

    登录并在开发者控制台中创建 API 密钥。

  2. 2

    发起请求

    将密钥作为 Bearer 令牌放在 Authorization 请求头中发送。

  3. 3

    获取数据

    接收包含商品数据和 QC 图片的 JSON 响应。

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/7231368393

认证

在 Authorization 请求头中使用 Bearer 方案附上有效的 API 密钥。

http
Authorization: Bearer qc_live_xxxxxxxxxxxxxxxxxxxxxxxx

密钥格式

密钥遵循 qc_{mode}_{random} 格式，其中 mode 为 live 或 test，而 random 是 32 个加密随机字符。

密钥仅在创建时显示一次。我们只存储 SHA-256 哈希值，因此丢失的密钥无法恢复 — 请撤销后重新创建一个。

IP 白名单

可选择通过开发者控制台将密钥限制为特定 IP 或 CIDR 范围。来自未列入白名单 IP 的请求会收到 403。空白名单则允许所有 IP。

速率限制

两类配额：每分钟 和 每月。你的分级会在每次请求时从账户读取 — 升级立即生效 — 且限制对你所有的密钥均适用。

分级/ 分钟/ 月
Basic301,000
Early Adopter403,000
Pro30025,000
Pro+1,000500,000
定制无限无限

/me 和 /usage 需要认证但不计入用量：查询自己的用量不会消耗你正查询的配额。

响应头

在每次响应中都会发送，不仅限于被拒绝的请求。

X-RateLimit-Limit你所在分级每分钟允许的请求数，或 "unlimited"。
X-RateLimit-Remaining当前这一分钟内剩余的请求数。
X-RateLimit-Reset距离拦截你的计数器重置还有多少秒。

触发速率限制时

API 会返回 429 — 每分钟突发限制对应 RATE_LIMITED，月度配额对应 QUOTA_EXCEEDED — 需等待的秒数在 retry_after 中给出。

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Per-minute rate limit exceeded",
    "retry_after": 37
  }
}

错误

错误会返回非 2xx 状态码，以及一个顶层 error 对象，包含稳定的 code 和 message。请匹配 code，而不是 message — message 可能会变化。

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found"
  }
}
400BAD_REQUEST请求正文或参数无效。
401INVALID_KEYAPI 密钥缺失、格式错误或未知。
401REVOKED_KEY该密钥已在控制台中被吊销。
403IP_NOT_AUTHORIZED请求 IP 不在该密钥的白名单中。
403FORBIDDEN你的分级无权访问此接口。
404NOT_FOUND请求的资源不存在。
429RATE_LIMITED已超过每分钟限制。
429QUOTA_EXCEEDED每月配额已用尽；将在 UTC 月度切换时重置。
500INTERNAL我们的问题，可放心使用退避策略重试。

接口

下方路径均相对于 https://backend.qualit.ly/api/v1。可用店铺为 weidian、taobao 和 1688。没有标签的接口在所有套餐下都可用。

获取商品

GET/products/{storefront}/{listing_id}

按店铺和 ID 查询单个商品。返回其元数据和最多 5 张 QC 预览缩略图。这是大多数接入方案最先用到的接口。

storefront必填string以下之一：weidian、taobao、1688。
listing_id必填string该店铺自身的商品 ID。

示例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/weidian/7231368393

响应

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "name": "AJ1 Retro High OG",
    "price": "¥470.00",
    "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
    "pic_gif": null,
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "qc_preview": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg"
    ]
  }
}

搜索商品

GET/products/search

按商品名称搜索目录 — 商品 URL 也会被匹配。不支持分页：每个套餐最多返回固定数量的结果。

q必填string搜索文本。多个词会以“与”逻辑同时匹配商品名称和商品 URL。
storefrontstring限定为 weidian、taobao 或 1688。
has_qcboolean仅返回有 QC 照片的商品。
limitinteger可要求少于你套餐上限的数量。超出上限的值会被下调，绝不会上调。

不支持分页。每个套餐每次搜索最多返回固定数量的结果；limit 只能要求更少，不能要求更多。

套餐最大结果数
Basic5
Early Adopter10
Pro50
Pro+100
定制250

示例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  "https://backend.qualit.ly/api/v1/products/search?q=jordan+1&storefront=weidian&has_qc=true&limit=10"

响应

json
{
  "query": "jordan 1",
  "count": 10,
  "limit": 10,
  "max_results": 100,
  "data": [
    {
      "id": 482910,
      "storefront": "weidian",
      "listing_id": "7231368393",
      "name": "AJ1 Retro High OG",
      "price": "¥470.00",
      "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
      "product_url": "https://weidian.com/item.html?itemID=7231368393",
      "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
      "qc_count": 12,
      "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
    }
  ]
}

字段

max_results你套餐的上限 — `limit` 会被限制到不超过这个上限。
count本次响应实际包含的行数。

批量商品

Pro+
POST/products/batch

一次调用最多解析 100 个商品。每一项都独立解析，因此缺失的商品不会导致整批失败 — 它会在原位置以错误条目的形式返回。

items必填array由 { storefront, listing_id } 对象组成的数组。上限为 100，若你套餐的单页上限更低，则以该上限为准。

请求正文

json
{
  "items": [
    { "storefront": "weidian", "listing_id": "7231368393" },
    { "storefront": "taobao", "listing_id": "123456789" }
  ]
}

示例

bash
curl -X POST \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"storefront":"weidian","listing_id":"7231368393"}]}' \
  https://backend.qualit.ly/api/v1/products/batch

响应

json
{
  "results": [
    {
      "data": {
        "id": 482910,
        "storefront": "weidian",
        "listing_id": "7231368393",
        "name": "AJ1 Retro High OG",
        "price": "¥470.00",
        "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
        "qc_count": 12,
        "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
      }
    },
    { "error": { "code": "NOT_FOUND" } }
  ]
}

随机商品

POST/products/random

一个带有 QC 照片的随机商品 — 适用于展示页、订阅流或抽样浏览目录。无需请求正文。

示例

bash
curl -X POST \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/products/random

响应

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "name": "AJ1 Retro High OG",
    "price": "¥470.00",
    "pic_url": "https://cdn.qualit.ly/covers/62743f38.jpg",
    "product_url": "https://weidian.com/item.html?itemID=7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "qc_preview": ["https://cdn.qualit.ly/qc/91c614ef.jpg"]
  }
}

QC 元数据

GET/qc/{storefront}/{listing_id}

某个商品的 QC 照片数量，加上前三张缩略图 — 无需拉取完整图片列表。

storefront必填string以下之一：weidian、taobao、1688。
listing_id必填string该店铺自身的商品 ID。

示例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/weidian/7231368393

响应

json
{
  "data": {
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "thumbnails": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg",
      "https://cdn.qualit.ly/qc/0f19ab77.jpg"
    ]
  }
}

QC 图片

Pro+
GET/qc/{id}/images

某个商品所有已收录的 QC 照片。可传入数字商品 ID，也可传入 ?url= 及任意受支持的商品链接，交由 API 解析。

id必填integer数字商品 ID。使用 ?url= 查询时传 0。
urlstring用于代替 ID 解析的完整商品 URL。传入时优先于 ID。

按商品 ID

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/qc/482910/images

按 URL

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  "https://backend.qualit.ly/api/v1/qc/0/images?url=https://weidian.com/item.html?itemID=7231368393"

响应

json
{
  "data": {
    "id": 482910,
    "storefront": "weidian",
    "listing_id": "7231368393",
    "qualitly_url": "https://qualit.ly/weidian/7231368393?utm_source=api&utm_content=key_7",
    "qc_count": 12,
    "images": [
      "https://cdn.qualit.ly/qc/91c614ef.jpg",
      "https://cdn.qualit.ly/qc/b66b2442.jpg"
    ]
  }
}

?url= 参数接受来自 Weidian、Taobao 和 1688 的商品链接，以及链接转换器支持的所有代购商链接。图片始终是 CDN URL。

账户信息

GET/me

你的账户、发起本次请求的密钥，以及它所对应的分级。可用作健康检查。

示例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/me

响应

json
{
  "user": { "id": 12345, "username": "you" },
  "key": { "id": 7, "mode": "live" },
  "tier": "pro_plus"
}

用量

GET/usage

你在两类速率限制配额中的当前状态，附带重置时间。和 /me 一样，这个接口需要认证但不计入用量 — 查询你的配额不会消耗它。

示例

bash
curl -H "Authorization: Bearer qc_live_YOUR_KEY" \
  https://backend.qualit.ly/api/v1/usage

响应

json
{
  "tier": "pro_plus",
  "key": { "id": 7, "mode": "live" },
  "minute": {
    "limit": 1000,
    "used": 12,
    "remaining": 988,
    "reset_in_seconds": 37,
    "reset_at": "2026-08-20T18:42:00.000Z"
  },
  "month": {
    "limit": 500000,
    "used": 1843,
    "remaining": 498157,
    "reset_in_seconds": 1159200,
    "reset_at": "2026-09-01T00:00:00.000Z",
    "bucket": 202608
  }
}

字段

tier以下之一：basic、early_adopter、pro、pro_plus、custom。
limit / remaining在 custom 分级上为 null（无限制）。
used当前窗口内计入的请求数。每分钟计数器每 60 秒重置一次；每月计数器在 UTC 月度切换时重置。
reset_atISO 8601，UTC。
bucket每月计数器的内部 YYYYMM 键。

代码示例

bash
curl -H "Authorization: Bearer $QUALITLY_KEY" \
  "https://backend.qualit.ly/api/v1/products/search?q=jordan+1&storefront=weidian"

MCP 服务器

同一套 API 也以托管的 Model Context Protocol 服务器形式提供，因此 Claude、Cursor、VS Code 或任何 MCP 客户端都可以查询商品和 QC 数据集，而无需编写 HTTP 请求。你的 API 密钥、速率限制和分级规则保持不变。

服务器 URL

https://backend.qualit.ly/api/mcp

传输方式

StreamableHTTP (POST)

认证

Authorization: Bearer qc_live_…

工具

只会注册你的分级能够调用的工具，因此 Basic 密钥永远不会看到一个会被拒绝调用的工具。

get_product按店铺和商品 ID 查询商品。
search_products按名称搜索，可按店铺和是否有 QC 照片筛选。
get_products_batch一次调用查询最多 100 个商品。Pro+
random_product带有 QC 照片的随机商品。
get_qcQC 数量和前 3 张缩略图。
get_qc_images完整 CDN 图片列表，按 ID 或 URL 查询。Pro+
get_me当前密钥、用户和分级。
get_usage每分钟和每月配额状态。

Claude Desktop、Cursor 和 VS Code

将服务器添加到 claude_desktop_config.json（Claude → 设置 → 开发者），或添加到你编辑器的 MCP 设置中。

Claude Desktop

json
{
  "mcpServers": {
    "qualitly": {
      "url": "https://backend.qualit.ly/api/mcp",
      "headers": {
        "Authorization": "Bearer qc_live_YOUR_KEY"
      }
    }
  }
}

Cursor / VS Code

json
{
  "mcp": {
    "servers": {
      "qualitly": {
        "url": "https://backend.qualit.ly/api/mcp",
        "headers": {
          "Authorization": "Bearer qc_live_YOUR_KEY"
        }
      }
    }
  }
}

支持 OAuth 自动发现的客户端 — 包括 Claude.ai 和 ChatGPT — 可以完全跳过硬编码密钥：未认证的请求会收到一个指向服务器 OAuth 元数据的 WWW-Authenticate 响应头，客户端会转而引导你的用户完成登录页授权。

验证可用性

bash
# List the tools your key can see
curl -X POST https://backend.qualit.ly/api/mcp \
  -H "Authorization: Bearer qc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

套餐与分级

你的分级会在每次请求时根据账户重新确定，因此升级从下一次调用起就会生效 — 无需换新密钥。批量查询、完整 QC 图片列表和 ?url= 提取是仅有的高于 Basic 才能使用的接口；其余的仅在额度上有所不同。

套餐/ 分钟/ 月搜索结果批量 + 图片
Basic301,0005
Early Adopter旧版403,00010
Pro30025,00050
Pro+1,000500,000100
定制无限无限250

Early Adopter 是旧版方案 — 由现有账户持有，不再对外销售。需要超出 Pro+ 的额度？[email protected] 可为你设置 Custom 限额。

查看完整套餐、定价和权益
搜索

Cookie

我们用它来保持登录状态并记住你保存的商品。只有在你同意后才会启用分析。