淘宝/天猫商品描述API（taobao.item_get_desc）返回值全面解析

是淘宝/天猫开放平台提供的核心商品详情接口之一，主要用于获取商品的详细描述信息。与接口相比，该接口更专注于返回商品详情页的图文描述内容，适用于需要展示商品完整介绍、规格参数、使用说明等场景。接口特点：专注描述信息：核心返回商品详情页的HTML描述内容图文分离：通常返回HTML文本，图片资源需要额外处理多语言支持：支持通过参数指定返回语言（中文/英文/俄文等）数据缓存：支持缓存机制，提升调用效率接口

APIshop

732人浏览 · 2026-02-27 17:32:21

APIshop · 2026-02-27 17:32:21 发布

一、接口概述

taobao.item_get_desc 是淘宝/天猫开放平台提供的核心商品详情接口之一，主要用于获取商品的详细描述信息。与 taobao.item.get 接口相比，该接口更专注于返回商品详情页的图文描述内容，适用于需要展示商品完整介绍、规格参数、使用说明等场景。

接口特点：

专注描述信息：核心返回商品详情页的HTML描述内容
图文分离：通常返回HTML文本，图片资源需要额外处理
多语言支持：支持通过参数指定返回语言（中文/英文/俄文等）
数据缓存：支持缓存机制，提升调用效率

二、请求参数详解

公共参数（Public Parameters）

参数名	类型	是否必填	说明
`key`	String	是	API调用密钥（App Key）
`secret`	String	是	API调用密钥（App Secret）
`api_name`	String	是	接口名称，固定为 `item_get_desc`
`cache`	String	否	是否使用缓存：`yes`（默认）/ `no`
`result_type`	String	否	返回格式：`json`（默认）/ `jsonu` / `xml` / `serialize`
`lang`	String	否	翻译语言：`cn`（默认中文）/ `en` / `ru`
`version`	String	否	API版本号

请求参数（Request Parameters）

参数名	类型	是否必填	说明
`num_iid`	String	是	淘宝/天猫商品数字ID

请求示例：

curl -i "https://api-gw.onebound.cn/taobao/item_get_desc/?key=<your_api_key>&secret=<your_api_secret>&num_iid=520813250866"

三、返回值结构全景

成功调用后，API返回标准的JSON数据结构，整体分为响应头信息、商品主体数据和错误信息三大部分。

3.1 顶层响应结构

{
    "request_id": "4f8c9d2e1a3b5f6e7d8c9b0a1f2e3d4c",
    "item": {
        "num_iid": "520813250866",
        "title": "2024新款夏季纯棉短袖T恤男女宽松百搭上衣",
        "price": "59.90",
        "desc": "<div class='detail-content'>...</div>",
        "desc_images": [...],
        "detail_url": "https://item.taobao.com/item.htm?id=520813250866",
        "shop_info": {...}
    },
    "error_response": null
}

3.2 核心字段详解

1. 请求追踪字段

字段名	类型	说明
`request_id`	String	请求唯一标识符，用于问题排查和日志追踪

2. 商品基础信息（item对象）

字段名	类型	示例值	说明
`num_iid`	Long	`520813250866`	商品唯一数字ID
`title`	String	`"2024新款夏季纯棉短袖T恤..."`	商品完整标题
`price`	String	`"59.90"`	商品当前售价（元）
`original_price`	String	`"89.00"`	商品原价（如有）
`promotion_price`	String	`"49.90"`	促销价（活动期返回）

3. 商品描述核心字段

字段名	类型	说明
`desc`	String	核心字段，商品详情HTML内容，包含图文混排、规格表、使用说明等
`desc_images`	Array	描述中包含的图片资源列表（部分版本支持）
`detail_url`	String	商品详情页原始链接

desc字段内容示例：

<div class="detail-content">
    <div class="detail-item">
        <h3>商品详情</h3>
        <p>精选100%纯棉面料，透气舒适...</p>
        <img src="//img.alicdn.com/imgextra/i1/xxx.jpg" />
    </div>
    <div class="detail-params">
        <table>
            <tr><th>品牌</th><td>XX服饰</td></tr>
            <tr><th>材质</th><td>100%棉</td></tr>
            <tr><th>尺码</th><td>S/M/L/XL/XXL</td></tr>
        </table>
    </div>
</div>

4. 描述图片资源（desc_images）

当接口支持返回结构化图片数据时，格式如下：

"desc_images": [
    {
        "url": "https://img.alicdn.com/imgextra/i1/2688/TB2abc123.jpg",
        "position": 1,
        "width": 750,
        "height": 800
    },
    {
        "url": "https://img.alicdn.com/imgextra/i2/2688/TB2def456.jpg", 
        "position": 2,
        "width": 750,
        "height": 800
    }
]

5. 店铺信息（shop_info）

字段名	类型	说明
`shop_id`	String	店铺ID
`shop_name`	String	店铺名称
`shop_type`	String	店铺类型：`taobao`（淘宝）/ `tmall`（天猫）
`score`	Float	店铺综合评分（如4.8）

四、扩展字段与特殊场景

4.1 SKU规格信息（部分版本）

部分API版本会在描述接口中返回SKU基础信息：

"skus": {
    "sku": [
        {
            "sku_id": "123456",
            "properties": "1627207:28341;20509:28314",
            "properties_name": "颜色:白色;尺码:M",
            "price": "59.90",
            "stock": 320,
            "outer_id": "SKU-001"
        }
    ]
}

4.2 促销与活动标签

促销信息可能以两种方式呈现：

结构化字段（部分版本支持）：

"promotion_price": "49.90",
"promotion_start_time": "2024-11-01 00:00:00",
"promotion_end_time": "2024-11-11 23:59:59",
"promotion_desc": "双11限时特惠"

HTML嵌入：在desc字段的HTML中通过特定class标识活动标签

4.3 错误响应结构

当请求失败时，error_response对象包含：

{
    "error_response": {
        "code": 40,
        "msg": "Insufficient isv permissions",
        "sub_code": "isv.permission-ip-whitelist-limit",
        "sub_msg": "IP白名单限制"
    }
}

常见错误码：

错误码	说明	解决方案
40	权限不足	申请相应API权限
7	参数错误	检查`num_iid`是否有效
15	频率限制	降低调用频率，申请更高QPS
27	无效密钥	检查App Key/Secret

五、数据处理与实战应用

5.1 HTML内容处理方案

由于desc字段返回的是HTML格式，需要特殊处理才能在前端安全展示：

5.2 完整调用示例（Python）

Python

复制

import requests
import time
import hashlib

def get_item_desc(app_key, app_secret, num_iid):
    """
    获取淘宝商品描述信息
    """
    url = "https://api-gw.onebound.cn/taobao/item_get_desc/"
    
    # 构造请求参数
    params = {
        'key': app_key,
        'secret': app_secret,
        'num_iid': num_iid,
        'cache': 'yes',
        'result_type': 'json',
        'lang': 'cn'
    }
    
    try:
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        
        data = response.json()
        
        # 检查错误
        if data.get('error_response'):
            error = data['error_response']
            print(f"API错误: {error.get('msg')}")
            return None
            
        item = data.get('item', {})
        
        # 提取核心数据
        result = {
            'item_id': item.get('num_iid'),
            'title': item.get('title'),
            'price': float(item.get('price', 0)),
            'description_html': item.get('desc'),
            'detail_url': item.get('detail_url'),
            'shop_name': item.get('shop_info', {}).get('shop_name'),
            'request_id': data.get('request_id')
        }
        
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"请求异常: {e}")
        return None

# 使用示例
if __name__ == "__main__":
    item_data = get_item_desc(
        app_key="your_app_key",
        app_secret="your_app_secret", 
        num_iid="520813250866"
    )
    
    if item_data:
        print(f"商品标题: {item_data['title']}")
        print(f"商品价格: ¥{item_data['price']}")
        print(f"描述长度: {len(item_data['description_html'])} 字符")