淘宝商品详情 API

Q: 商品有多个规格时价格怎么看？

skus 是全部规格列表，每条可以带自己的价格、原价、券后价和库存；price 是商品层面的价格。比价或监测时按规格逐条记录，别只记一个价格；spec_values 还给出包括未在售组合在内的全部规格值。

Q: 详情页的图文介绍能拿到吗？

能。description_images 是详情区的长图列表，按页面出现顺序排列；description_html 是详情区的原始 HTML，以图片标签为主。主图在 main_image_url，主图视频在 video_url，没有视频时这个字段不出现。

POST

接口健康状态

24h 健康值: 86%
24h 平均耗时: 13.45 s

健康 / 正常
可用
少量可用
基本不可用

可用

24 小时趋势

30 天趋势

商品详情：返回单个对象；主要字段 id、url、title、brand、price、original_price。

淘宝商品详情读取一件淘宝或天猫商品的完整公开信息：标题、品牌、价格与原价、券后价、库存与销量、全部规格及各自的价格和库存、商品属性、主图与详情长图，以及店铺和运费。它回答「这件商品到底卖什么、怎么定价」，适合竞品拆解、价格与促销监测、比价和商品库补全。

url 可以传商品数字 ID、商品链接，或含唯一商品链接的分享文本；纯淘口令和过期链接会被拒绝。看价格时注意 coupon_price 只在有券时出现，skus 里每个规格可能单独定价；is_tmall 区分天猫店和淘宝店，两者的开店门槛和保障不同。

单价 $1.39 / 千次（每次 $0.001389），失败与空结果不扣费。同步返回；慢任务可在请求体加 "mode": "async"，先拿 job_id 再轮询。

AI 提示词

复制下面这段给你常用的 AI 助手：里面写好了这个接口的参数、返回字段和示例请求，它会先问清你的需求，再帮你写采集脚本。

请帮我用 EveryInfra 的「淘宝商品详情」接口（taobao/product_detail）写一个数据采集脚本。

接口约定：
- 请求：POST https://api.everyinfra.com/api/v1/social，请求头 Authorization: Bearer <API Key>；Key 从环境变量 EVERYINFRA_API_KEY 读取，不要写进代码。
- 请求体里 platform 填 taobao，action 填 product_detail，参数放在 params 里。
- 必填参数：
  - url：product_detail / reviews / questions 接收商品数字 ID、淘宝/天猫商品 URL，或含唯一商品 URL 的分享文本。
- 返回一个对象，主要字段：id、url、title、brand（品牌）、price、original_price（原价）、currency、stock（库存）、sold_count（销量）、category_id（类目 ID）、location、is_tmall（是否为天猫店（区别于淘宝 C 店）；一共 76 个字段，完整列表见 https://api.everyinfra.com/api/v1/social/catalog?platform=taobao。
- 示例请求体：
{
  "platform": "taobao",
  "action": "product_detail",
  "params": {
    "url": "https://item.taobao.com/item.htm?id=744983869996"
  }
}
- 计费：$1.39 / 千次；失败和空结果不扣费。
- 一次要采几十上百个时，在请求体加 "mode": "async"：先拿到 job_id，再轮询 GET https://api.everyinfra.com/api/v1/jobs/{job_id} 取结果。
- 返回 422 时，按错误信息里的候选参数和允许值修正；返回 429 或 503 时，按 Retry-After 等待后重试。

写代码前，先问清楚我要采哪些对象、一共多少个、需要哪些字段、结果存成什么格式，再把方案和大概花费讲给我确认。

请求参数

参数名	位置	类型	必填	默认值	说明
`Authorization`	header	`string`	是	-	Bearer 加你的 API Key。在控制台创建；不要放进网址或代码仓库。
`platform`	body	`string`	是	`taobao`	平台标识，固定值。
`action`	body	`string`	是	`product_detail`	能力标识，固定值。
`url`	body.params	未声明	是	-	product_detail / reviews / questions 接收商品数字 ID、淘宝/天猫商品 URL，或含唯一商品 URL 的分享文本；e.tb.cn / m.tb.cn 短链仅在可安全解析为商品页时接受。纯淘口令、过期链接和非商品页会拒绝。

代码示例

bash

curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "taobao",
  "action": "product_detail",
  "params": {
    "url": "https://item.taobao.com/item.htm?id=744983869996"
  }
}'

[OpenAPI 定义 (JSON)]示例从环境变量 EVERYINFRA_API_KEY 读取 Key，复制出去的代码不含你的 Key。

响应示例

字段预览

这组示例参数还没有真实样例：这里只按契约列出响应结构和字段，值用 … 占位，不是一次真实调用的结果。

json

{
  "id": "req_…",
  "platform": "taobao",
  "action": "product_detail",
  "results": {
    "id": …,
    "url": …,
    "title": …,
    "brand": …,
    "price": …,
    "original_price": …,
    "currency": …,
    "stock": …,
    "sold_count": …,
    "category_id": …,
    "location": …,
    "is_tmall": …,
    "shop_name": …,
    "shop_id": …,
    "shipping_fee": …,
    "ems_fee": …,
    "express_fee": …,
    "skus": …,
    "sku_count": …,
    "spec_values": …,
    "props_images": …,
    "attributes": …,
    "main_image_url": …,
    "description_images": …,
    "description_html": …,
    "video_url": …,
    "coupon_price": …,
    "price_usd": …,
    "total_price": …,
    "suggestive_price": …,
    "has_discount": …,
    "is_promotion": …,
    "promo_type": …,
    "is_virtual": …,
    "brand_id": …,
    "root_category_id": …,
    "category_path": …,
    "weight": …,
    "size": …,
    "favorite_count": …,
    "fans_count": …,
    "min_order_quantity": …,
    "shipping_to": …,
    "listed_at": …,
    "modified_at": …,
    "delist_at": …,
    "images": …,
    "category_name": …,
    "description": …,
    "keywords": …,
    "titleOriginal": …,
    "has_cn_title": …,
    "shop_score_description": …,
    "shop_score_service": …,
    "shop_score_delivery": …,
    "free_shipping": …,
    "promotion_price": …,
    "discount_price": …,
    "discount_type": …,
    "price_note": …,
    "has_price_range": …,
    "payment_methods": …,
    "seller_id": …,
    "seller_credit_level": …,
    "seller_type": …,
    "seller_type_label": …,
    "selling_points": …,
    "shop_logo_url": …,
    "shop_url": …,
    "shop_item_count": …,
    "shop_new_item_count": …,
    "shop_opened_at": …,
    "review_tags": …,
    "review_count": …,
    "positive_rate": …,
    "seven_day_return": …,
    "platform": …
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}

返回字段

业务数据在 results 里；下表是每条记录可能包含的字段，平台没有提供的值不会被补造。

字段	含义
`id`	该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。
`url`	该记录在原平台上的可访问链接。
`title`	标题。平台无标题概念时（如纯文本帖）为 null。
`brand`	品牌。
`price`	价格数值，不含货币符号；币种见 currency。
`original_price`	原价。
`currency`	价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。
`stock`	库存。
`sold_count`	销量。
`category_id`	类目 ID。
`location`	地理位置描述，原文透传，格式随平台而异。
`is_tmall`	是否为天猫店（区别于淘宝 C 店，开店门槛和保障不同）。
`shop_name`	店铺名。
`shop_id`	店铺 ID（search 行与详情、店铺商品行同一口径）。
`shipping_fee`	运费。
`ems_fee`	EMS 运费。
`express_fee`	快递运费。
`skus`	规格列表（全量，有多少给多少）。每条可含 id/name/price/original_price/coupon_price/stock/props_ids/image_url。
`sku_count`	SKU 数量。
`spec_values`	商品规格值全表（含未在售组合），id 为规格值标识、text 为规格文本。
`props_images`	规格值配图，id 与 spec_values/props_ids 同一标识，image_url 为该规格的展示图。
`attributes`	商品属性列表（品牌、型号、产地等 {name, value} 行）。
`main_image_url`	主图（首图）。
`description_images`	详情页描述区长图列表（按页面出现顺序）。
`description_html`	详情页描述区原始 HTML（以图片标签为主）。
`video_url`	主图视频直链（无视频时缺省）。
`coupon_price`	券后价（有优惠券时低于 price，无券时缺省）。
`price_usd`	美元参考价（按返回数据中的折算值）。
`total_price`	总价（以返回数据为准，常缺省）。
`suggestive_price`	建议零售价（常缺省）。
`has_discount`	是否有折扣。
`is_promotion`	是否促销中。
`promo_type`	促销类型。
`is_virtual`	是否虚拟商品。
`brand_id`	品牌 ID。
`root_category_id`	根类目 ID。
`category_path`	类目路径（面包屑）。
`weight`	商品重量（以返回数据为准，常为 0 或缺省）。
`size`	商品尺寸（常缺省）。
`favorite_count`	收藏数。
`fans_count`	粉丝数（以返回数据为准，常缺省）。
`min_order_quantity`	最小起订量。
`shipping_to`	配送范围说明（常缺省）。
`listed_at`	上架时间（ISO 8601，数据缺省时字段不出现）。
`modified_at`	最近修改时间（ISO 8601，数据缺省时字段不出现）。
`delist_at`	下架时间（ISO 8601，数据缺省时字段不出现）。
`images`	图片链接列表：product_detail 是商品图，reviews 是买家晒图（没晒图时没有这个字段）。
`category_name`	叶子类目名（product_detail）。
`description`	简介或描述，通常比 text 短。
`keywords`	商品页关键词（product_detail）。
`titleOriginal`	保留平台原语义
`has_cn_title`	保留平台原语义
`shop_score_description`	店铺动态评分·描述相符（5 分制）。
`shop_score_service`	店铺动态评分·服务态度（5 分制）。
`shop_score_delivery`	店铺动态评分·物流服务（5 分制）。
`free_shipping`	是否包邮。
`promotion_price`	促销价（product_detail，常缺省）。
`discount_price`	折后价（product_detail，常缺省）。
`discount_type`	折扣/活动类型原文（如「特价秒杀」）。
`price_note`	价格说明原文（product_detail）。
`has_price_range`	是否区间价（多规格价格不同，product_detail）。
`payment_methods`	支持的支付方式（product_detail）。
`seller_id`	卖家 ID。
`seller_credit_level`	卖家信用等级（数字，越大越高）。
`seller_type`	卖家类型代码（product_detail）。
`seller_type_label`	卖家类型名称（product_detail，如天猫、企业店）。
`selling_points`	商品卖点标签列表。
`shop_logo_url`	店铺 Logo 链接（product_detail）。
`shop_url`	店铺链接（product_detail）。
`shop_item_count`	店铺在售商品数（product_detail）。
`shop_new_item_count`	店铺新品数（product_detail）。
`shop_opened_at`	开店时间原文（product_detail）。
`review_tags`	评价标签列表，每项 tag（标签文字）与 count（提到次数，可能缺省）。
`review_count`	评价条数，用于商品/商家类能力。null 表示不公开，不等于 0。
`positive_rate`	商品好评率（product_detail，百分数，常缺省）。
`seven_day_return`	是否支持七天无理由退货（product_detail）。
`platform`	数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。

常见问题

`url` 能填哪些东西？

商品数字 ID、淘宝或天猫的商品链接，或者含唯一商品链接的分享文本都可以；e.tb.cn、m.tb.cn 短链只在能安全解析到商品页时接受。纯淘口令、过期链接和店铺页、搜索页等非商品页会被拒绝。

商品有多个规格时价格怎么看？

skus 是全部规格列表，每条可以带自己的价格、原价、券后价和库存；price 是商品层面的价格。比价或监测时按规格逐条记录，别只记一个价格；spec_values 还给出包括未在售组合在内的全部规格值。

详情页的图文介绍能拿到吗？

能。description_images 是详情区的长图列表，按页面出现顺序排列；description_html 是详情区的原始 HTML，以图片标签为主。主图在 main_image_url，主图视频在 video_url，没有视频时这个字段不出现。

错误与计费

401: 缺少 Key 或 Key 无效。先鉴权再校验参数，未鉴权的请求拿不到参数结构。
422: 参数名或取值不对。错误信息会列出这项能力支持的参数、允许值和最接近的候选，按它改即可；发生在扣费之前。
402: 余额不足，请先充值。
429: 超过账户的每分钟请求上限（名下所有 Key 合计；Key 自设了更低上限时先按它算），按 Retry-After 等待后再试。需要更高上限可在控制台买提速包。
503: 暂时无法完成。已预扣的费用按原账本退回；响应里的 billing 与 refund 写明实际结果，结果未知时会明确标出，不要直接重发。
200 空结果: 请求完成但没有数据，不扣费（billing.reason = empty_result_refunded）。