# 淘宝 商品详情 API (taobao.product_detail)

- Canonical page: https://everyinfra.com/taobao-api/product_detail
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "taobao", "action": "product_detail", "params": {...}}
- Price: $0.0045 per call ($4.5 per 1,000 requests); failed calls and empty results are not charged
- Returns: single object
- Mode: sync; add "mode": "async" for slow tasks

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

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

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=taobao&action=product_detail

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| url | not declared | yes | not declared | product_detail / reviews / questions 接收商品数字 ID、淘宝/天猫商品 URL，或含唯一商品 URL 的分享文本；e.tb.cn / m.tb.cn 短链仅在可安全解析为商品页时接受。纯淘口令、过期链接和非商品页会拒绝。同步调用最长约 85 秒，客户端超时建议不低于 95 秒。product_detail 查询的商品已下架或不存在时返回空结果，empty_reason 为 item_not_found，不扣费。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| title | 标题。平台无标题概念时（如纯文本帖）为 null。 |
| brand | 品牌（product_detail 常缺省）。 |
| price | 价格数值，不含货币符号；币种见 currency。product_detail 的价格（含 skus 每条的 price）有两种：淘宝页面上的人民币价，或由美元价折算成的人民币价（可能比页面价高或低约 1–4%，以页面为准）。search 每行的价可能是页面现价、划线价或推广价。是哪种见 price_basis。 |
| original_price | 原价（划线价）；search 无折扣时与 price 相同。product_detail 多数调用为空。shop 只有这一个价：列表展示的划线价，不是实际卖价，可能明显偏高；要卖价用 product_detail。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| price_basis | price 是怎么来的（有价才给）。product_detail：page 是淘宝页面上的人民币价；converted 是由美元价折算成的人民币价，可能比淘宝页面上的价格高或低约 1–4%。search（每行一个）：page 是淘宝页面上的现价；list 是划线价，商品打折时高于实际卖价，有时高出一倍；promotion 是淘宝推广价，常比页面价低很多。currency 都是 CNY；同一商品不同次调用可能不同。 |
| stock | 库存件数。卖家有多个仓时，同一商品不同次调用给出的库存可能不同（发货地也可能不同）。product_detail 的来源没给整件库存时，给的是各规格库存的合计。 |
| sold_count | 销量（search 有；product_detail 只有一部分调用会返回，占比每天不同）。 |
| category_id | 类目 ID。 |
| location | 发货地。卖家有多个仓时，同一商品不同次调用给出的发货地可能不同。 |
| is_tmall | 是否为天猫店（区别于淘宝 C 店，开店门槛和保障不同）。product_detail 的部分来源不给这一项。 |
| shop_name | 店铺名。 |
| shop_id | 店铺 ID（search 行与详情、店铺商品行里是同一个 ID）。 |
| shipping_fee | 运费。product_detail 多数调用为空。 |
| ems_fee | EMS 运费。product_detail 多数调用为空。 |
| express_fee | 快递运费。product_detail 多数调用为空。 |
| skus | 规格列表（全量，有多少给多少）。每条可含 id/name/price/original_price/coupon_price/stock/props_ids/image_url；price 可能是折算价，见 price。 |
| sku_count | SKU 数量。 |
| spec_values | 商品规格值全表（含未在售组合），id 为规格值标识、text 为规格文本。 |
| props_images | 规格值配图，id 与 spec_values/props_ids 同一标识，image_url 为该规格的展示图。 |
| attributes | 商品属性列表（品牌、型号、产地等 {name, value} 行）。 |
| main_image_url | 主图（首图）。在商品详情（product_detail）里，主图和图集 `images` 都没有时这次调用不扣费，其余数据照常返回。 |
| description_images | 详情页描述区长图列表（按页面出现顺序）。product_detail 有的调用为空。 |
| description_html | 详情页描述区原始 HTML（以图片标签为主）。product_detail 有的调用为空。 |
| video_url | 主图视频直链。目前基本取不到主图视频，这个字段多半为空；为空不代表商品没有视频。 |
| coupon_price | 券后价（有优惠券时低于 price，无券时缺省）。product_detail 只有一部分调用会返回这一项（占比每天不同），缺省不一定是没有券。 |
| price_usd | 美元参考价（按返回数据中的折算值）。product_detail 多数调用为空。 |
| total_price | 总价（以返回数据为准，常缺省）。 |
| suggestive_price | 建议零售价（常缺省）。 |
| has_discount | 是否有折扣。product_detail 多数调用为空。 |
| is_promotion | 是否促销中。product_detail 多数调用为空。 |
| promo_type | 促销类型。 |
| is_virtual | 是否虚拟商品。product_detail 多数调用为空。 |
| brand_id | 品牌 ID。 |
| root_category_id | 根类目 ID。 |
| category_path | 类目路径（面包屑，用「 > 」连接；product_detail 与 search 都可能有）。 |
| weight | 商品重量（以返回数据为准，常为 0 或缺省）。product_detail 多数调用为空。 |
| size | 商品尺寸（常缺省）。 |
| favorite_count | 收藏数。 |
| fans_count | 店铺粉丝数（product_detail 常缺省）。 |
| min_order_quantity | 最小起订量。product_detail 多数调用为空。 |
| shipping_to | 配送范围说明（常缺省）。 |
| listed_at | 上架时间（ISO 8601，数据缺省时字段不出现）。 |
| modified_at | 最近修改时间（ISO 8601，数据缺省时字段不出现）。 |
| delist_at | 下架时间（ISO 8601，数据缺省时字段不出现）。 |
| images | 图片链接列表：product_detail、search 是商品图（search 不含主图 image_url），reviews 是买家晒图（没晒图时没有这个字段）。 |
| category_name | 叶子类目名（product_detail）。 |
| description | 简介或描述，通常比 text 短。 |
| keywords | 商品页关键词（product_detail）。 |
| titleOriginal | platform-native meaning |
| has_cn_title | platform-native meaning |
| 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（shop 偶尔缺；product_detail 的部分来源不给）。 |
| seller_credit_level | 卖家信用等级（数字，越大越高）。 |
| seller_type | 卖家类型代码（product_detail、search；B 为天猫或企业店，C 为个人店）。 |
| seller_type_label | 卖家类型名称（product_detail，如天猫、企业店）。 |
| selling_points | 商品卖点标签列表。 |
| shop_logo_url | 店铺 Logo 链接（product_detail、shop；shop 偶尔缺）。 |
| shop_url | 店铺链接（product_detail、shop）。 |
| shop_item_count | 店铺在售商品数（product_detail、search、shop）。 |
| shop_new_item_count | 店铺新品数（product_detail）。 |
| shop_opened_at | 开店时间原文（product_detail、search）。 |
| review_tags | 评价标签列表，每项 tag（标签文字）与 count（提到次数，可能缺省）。 |
| review_count | 评价条数，用于商品/商家类能力。null 表示不公开，不等于 0。 |
| positive_rate | 好评率（百分数，98.93 即 98.93%）：product_detail 是商品好评率（常缺省）。 |
| seven_day_return | 是否支持七天无理由退货（product_detail）。 |
| reviews | 商品页附带的买家评价（product_detail），每条与 reviews 接口的行同形：text、rating、posted_at、sku、author_name、author_avatar_url 等，文本为简体；只是页面上展示的几条，要按条数取全请调 reviews。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |

## Example

```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"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "taobao",
        "action": "product_detail",
        "params": {
            "url": "https://item.taobao.com/item.htm?id=744983869996",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "taobao",
  "action": "product_detail",
  "results": {
    "id": "•••",
    "url": "https://item.taobao.com/item.htm?id=744983869996",
    "title": "绿联转换插头英标韩国马来西亚澳洲新加坡新西兰Switch转换器充电",
    "price": 29.97,
    "currency": "CNY",
    "stock": 1397,
    "category_id": "50003472",
    "location": "廣東東莞",
    "is_tmall": true,
    "shop_name": "绿联数码旗舰店",
    "shop_id": "67095450",
    "skus": [
      {
        "id": "•••",
        "name": "[for Outings] English to Chinese Converter|Matte Black⭐Applicable to Hong Kong/Macau/Malaysia/Singapore, China",
        "price": 30.17,
        "stock": 200,
        "image_url": "https://img.alicdn.com/bao/uploaded/i3/713464357/O1CN01QOFAISCEu2L1chua_!!713464357.jpg"
      },
      {
        "id": "•••",
        "name": "[for Outings] English to Chinese Converter|Lightweight White⭐Applicable to Hong Kong/Macau/Malaysia/Singapore, China",
        "price": 29.97,
        "stock": 200,
        "image_url": "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01P9gIa5t80pC1chua_!!713464357.jpg"
      },
      {
        "id": "•••",
        "name": "[for Mainland China] Chinese to English Converter|Matte Black⭐Applicable to Hong Kong Version of Ps5/Switch2/Electrical Appliances in Hong Kong and Macau, China",
        "price": 30.17,
        "stock": 200,
        "image_url": "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01WLbh5e1i3YjKWsf7g_!!713464357.jpg"
      }
    ],
    "sku_count": 8,
    "main_image_url": "https://img.alicdn.com/bao/uploaded/i4/713464357/O1CN01Cr4DMB1i3YoKXb4bM_!!4611686018427386405-0-item_pic.jpg",
    "description_images": [
      "https://img.alicdn.com/imgextra/i1/713464357/O1CN01tRpmSz1MdQI1WPZ8_!!713464357.jpg",
      "https://img.alicdn.com/imgextra/i1/713464357/O1CN019muBmB1i3YpL3L8sM_!!713464357.jpg",
      "https://img.alicdn.com/imgextra/i3/713464357/O1CN011J4LMz1i3Ynq3SQ1z_!!713464357.jpg"
    ],
    "price_usd": 5.27,
    "root_category_id": "50020579",
    "category_path": "首页 > 电子/电工 > 接线板/插头 > 转换插头",
    "min_order_quantity": 1,
    "images": [
      "https://img.alicdn.com/bao/uploaded/i4/713464357/O1CN01Cr4DMB1i3YoKXb4bM_!!4611686018427386405-0-item_pic.jpg",
      "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01f4WmsN1i3YoKlcotr_!!713464357.jpg",
      "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01KQ3NjW1i3YljOLkIv_!!713464357.jpg"
    ],
    "category_name": "转换插头",
    "description": "港版Switch转换插头 - 英标转中转换器，适用马来西亚插头与多国转换插头，具备65W快充功能。适合港版Switch 1与2使用，提供全球适用的转换解决方案。\n\n多国适用与高效快充功能 - 绿联多国转换插头支援英标、美标、德标与澳标等多种插头类型，适用全球多数国家与地区。内建65W快充技术，确保高功率需求的装置如Switch主机与笔电能快速充电，同时具备安全保护机制，避免过载与短路。\n\n多样款式与便利设计选择 - 转换插头提供多种款式选择，包含单独英转中、中转英与多合一组合。特别针对港版Switch 2使用者设计，提供适用进口电器的转换方案。轻巧便携设…",
    "keywords": [
      "港版Switch转换插头",
      "英标转中转换器",
      "适用马来西亚插头"
    ],
    "shop_score_description": 4.8,
    "shop_score_service": 4.8,
    "shop_score_delivery": 4.9,
    "free_shipping": false,
    "has_price_range": true,
    "payment_methods": [
      "蚂蚁花呗",
      "信用卡支付",
      "集分宝"
    ],
    "seller_id": "•••",
    "seller_credit_level": 20,
    "seller_type": "B",
    "seller_type_label": "Business seller",
    "selling_points": [
      "港版Switch2转换插头:专为港版Switch2设计转换插头，兼容多国电压，出国携带无烦恼。",
      "绿联品牌认证转换器:知名电子品牌绿联出品，通过多国安全认证，使用更安心。",
      "多国插头规格适用:适用马来西亚、新加坡、英国等多国插座标准，国际旅行首选。"
    ],
    "shop_logo_url": "https://img.alicdn.com/imgextra//d2/82/TB1rBsXkkL0gK0jSZFASuwA9pXa.jpg",
    "shop_url": "https://shop.m.taobao.com/shop/shop_index.htm?user_id=713464357",
    "shop_item_count": 1330,
    "shop_new_item_count": 28,
    "shop_opened_at": "2011-05-30 14:37:22",
    "seven_day_return": false,
    "reviews": [
      {
        "text": "还不错，通电了装换头会有提示灯 没送收纳袋。 体积挺小巧的。 手感挺细腻的。",
        "rating": 5,
        "posted_at": "2026.10.17 18:07",
        "sku": "颜色:【内地用】中转英转换器|轻骑白⭐港版PS5/Switch2/中国香港澳门地区电器适用",
        "author_avatar_url": "https://gw.alicdn.com/•••"
      }
    ],
    "platform": "taobao"
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### `url` 能填哪些东西？

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

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

`skus` 是全部规格列表，每条可以带自己的价格、原价、券后价和库存；`price` 是商品层面的价格。比价或监测时按规格逐条记录，别只记一个价格；`spec_values` 还给出包括未在售组合在内的全部规格值。这些价格有两种：淘宝页面上的人民币价，或由美元价折算成的人民币价（可能比页面价高或低约 1–4%，以页面为准）；每次调用拿到的是哪种看 `price_basis`。

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

多数时候能。`description_images` 是详情区的长图列表，按页面出现顺序排列；`description_html` 是详情区的原始 HTML，以图片标签为主；这两项有的调用会是空的。主图在 `main_image_url`；主图视频在 `video_url`，但目前基本取不到，这个字段多半为空，为空不代表商品没有视频。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=taobao
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
