推出 Commerce Product

传入 Amazon、Walmart、Sephora、Olive Young、Rakuten、Zalando 等 17 家电商平台的商品页面 URL，以同一格式获取价格、库存、商品图和详情图、规格和选项。

获得的结果

• COMMERCE_PRODUCT：一个任务读取一个商品页面，支持美国、韩国、日本、印度和德国的 17 家平台。传入页面的 url 即可确定平台。
• 按页面显示返回 title、brand、带 currency 的 price 和 listPrice，以及 inStock、seller、rating 和 reviewCount。
• images 是商品图库；descriptionImages 按页面顺序收录商品描述中的图片，例如卖家的详情页或 Amazon 的 A+ 内容。
• description、specs、options、categories 和 gtin 在所有平台都使用相同字段。

支持的平台

• 美国（US）：Amazon amazon、Walmart walmart、Target target、Sephora sephora、Ulta ulta
• 韩国（KR）：Olive Young oliveyoung、11st 11st、Lotte ON lotteon、Musinsa musinsa、Kurly kurly
• 日本（JP）：Rakuten rakuten、Yahoo! Shopping yahoo_shopping、Qoo10 qoo10
• 印度（IN）：Flipkart flipkart、Myntra myntra、Nykaa nykaa
• 德国（DE）：Zalando zalando

工作原理

每个任务从平台所在国家读取商品页面，并按页面默认打开的选项返回数值。price 是使用优惠券和运费之前支付的价格，options 列出其他尺寸、颜色或套装。

images 收录图库中最多 30 张照片，descriptionImages 按页面顺序收录商品描述中最多 300 张图片。详情图来自 Amazon、Ulta、Olive Young、11st、Lotte ON、Musinsa、Kurly、Rakuten、Yahoo! Shopping 和 Qoo10。卖家放在其中的横幅和公告也会一并返回，图片中的文字保留在图片里。

title、price、currency 和 images 来自所有平台，其他字段在页面显示时返回；各字段支持的平台列在引擎文档中。平台答复为已下架的商品页面时，任务以 PAGE_UNAVAILABLE 结束。

应用场景

• 详细读取 Commerce Search 排名靠前的商品：价格、库存、卖家和全部选项。
• 每天追踪自家商品页面在 Amazon、Olive Young 和 Rakuten 上的价格、原价和库存。
• 收集竞品的商品图和详情图，比较各品牌如何展示同一类商品。
• 把规格、选项和详情图用于商品目录或 AI 购物回答的检查。

发送请求

在 Authorization 请求头中带上 API 密钥发送请求。

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "COMMERCE_PRODUCT",
    "payload": { "url": "https://www.amazon.com/dp/B00TTD9BRC" }
  }'

请求字段

taskTypestring必填

要运行的引擎，例如 CHATGPT 或 GOOGLE。

payload.urlstring必填

17 家平台之一的商品页面，最多 2,048 个字符。URL 决定平台及其国家。

payload.countrystring

平台所在的国家，例如 Amazon 为 US，Olive Young 为 KR。省略时也使用此值。

webhook.urlstring

你服务器上的 HTTPS 地址。任务完成后立即把结果推送到这里。

响应

完成的任务如下所示，已截取部分内容。

{
  "success": true,
  "task": {
    "id": "3f0f65f4-bb08-492b-8652-7037fe7cba0d",
    "taskType": "COMMERCE_PRODUCT",
    "status": "COMPLETED",
    "createdAt": "2026-10-22T09:27:29.765Z"
  },
  "credits": { "creditsToCharge": 3, "creditsCharged": 3 },
  "response": {
    "site": "amazon",
    "country": "US",
    "url": "https://www.amazon.com/dp/B00TTD9BRC",
    "productId": "B00TTD9BRC",
    "title": "CeraVe Moisturizing Cream, Face & Body Moisturizer for Dry Skin, 19oz",
    "brand": "CeraVe",
    "price": 18.39,
    "currency": "USD",
    "inStock": true,
    "seller": "Amazon.com",
    "rating": 4.7,
    "reviewCount": 149176,
    "images": [
      "https://m.media-amazon.com/images/I/61EidjXUBrL._SL1000_.jpg",
      "https://m.media-amazon.com/images/I/61-Ut3jOyyL._SL1500_.jpg",
      "…"
    ],
    "descriptionImages": [
      "https://m.media-amazon.com/images/S/aplus-media-library-service-media/8c56d081-e316-4b57-9731-fcf4eda0821f.__CR0,0,1464,600_PT0_SX1464_V1___.jpg",
      "…"
    ],
    "specs": [
      { "name": "Brand Name", "value": "CeraVe" },
      { "name": "Skin Type", "value": "All, Dry, Sensitive" },
      "…"
    ],
    "options": [
      {
        "name": "Size",
        "values": [
          "8 Ounce",
          "16 Ounce (Pack of 1)",
          "19 Ounce (Pack of 1)",
          "…"
        ]
      }
    ],
    "categories": ["Beauty & Personal Care", "Skin Care", "Face", "…"]
  }
}

task.statusstring

依次为 QUEUED、PROCESSING，最终为附带回答的 COMPLETED 或附带 error 的 FAILED。

credits.creditsChargedinteger

已完成任务扣除的积分。失败的任务为 0。

response.pricenumber

页面首先展示的商品在优惠券和运费之前的价格，单位为 currency（ISO 4217）。listPrice 是高于 price 时页面划线显示的原价。

response.imagesarray

商品图库中的照片，按页面顺序，最多 30 张。

response.descriptionImagesarray

商品描述中的图片，例如卖家的详情页或 Amazon 的 A+ 内容，按页面顺序，最多 300 张。

response.specsarray

商品详情中的 { name, value } 对，最多 100 组。options 列出尺寸、颜色等选项及其 values。

获取结果

请求会立即返回 status 为 QUEUED 的任务。用 GET /v1/async/task/{id} 轮询，直到 status 变为 COMPLETED 或 FAILED；或者加上 webhook.url，在服务器上接收同样的 task、credits 和 response。任务结束后，结果保留 24 小时供查询。

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

错误

VALIDATION_ERRORHTTP 422

缺少 url、超过 2,048 个字符或不是 17 家平台的商品页面，或 payload 带有 url 和 country 以外的字段。details 会指明该字段。

REGION_UNSUPPORTEDHTTP 422

country 与平台所在国家不同，例如 Amazon URL 配 KR。

MISSING_API_KEYHTTP 401

缺少 Authorization 请求头，或密钥有误、已过期或已吊销。

INSUFFICIENT_CREDITSHTTP 402

余额低于任务价格。充值积分或升级套餐后再发送。

价格

所有平台每完成一次商品页面读取消耗 3 积分。积分在任务完成时扣除。