实战解析：1688详情api商品sku、主图数据

1688 商品详情 API 的 SKU 与主图数据，是大多数选品、铺货、比价系统首先要啃下的两块"硬骨头"。下面用一条完整的实战链路，把"拿到商品 ID → 拉出 SKU → 拖走主图"过程中最容易踩的坑、最实用的代码、以及返参里那些看似人畜无害却暗藏杀机的字段一次性讲透。

一、接口选型：item_get 还是 sku_get？

只想一次性拿"商品级"数据（标题、主图、最低价、起批量、供应商信息）

直接调 alibaba.item.get（或第三方包装的 /1688/item_get/）即可，SKU 会作为子节点嵌在 sku_list 数组里。
已经拿到商品 ID 列表，只想批量刷新价格/库存

再单独调 alibaba.item.sku.get 可省流量，但官方 QPS 卡得死（默认 1），高并发场景建议先在本地建"SKU 池"，再定时用 item_get 做增量更新。

二、SKU 数据到底长什么样？

以 2025-12 官方文档示例为例，一个 SKU 节点核心字段只有 4 个，但坑都在"单位"和"空值"里：

javascript 复制代码

{
  "sku_id": "987654321012",
  "sku_spec": "白色-L",
  "sku_price": "19.90",     // 字符串，需自己转 float
  "sku_stock": 5000         // 单位是"件"，不是"箱"！
}

实战注意

价格字段 sku_price 返回的是"单件批发价"，再乘以 min_order_quantity 才是真正的起批金额。
库存 sku_stock 只是"展示库存"，真实可售库存要看 available_stock（同一节点下若有该字段）。
部分类目（包装制品、化工）会把"箱/桶"作为销售单位，spec 里会出现 "1箱=1 200件" 的映射，需要自己做正则拆分。
当商品开启"阶梯价"时，SKU 里不会给出 2 件、10 件的批发价，需要再调用 alibaba.cpsMedia.productInfo 或爬取 H5 页面解析 priceRange 字段。

三、主图、SKU 图、详情图 3 张皮

item_get 一次会给 3 组图片，很多人直接 for img in item_imgs 就完事，结果上线后发现 30 天后全变 403------官方图片链接带 token，有效期 30 天，长期用必须落盘。

python 复制代码

# 伪代码：一键落盘 3 类图
def dump_images(item):
    folders = ['主图', 'SKU图', '详情图']
    img_lists = [
        [item['pic_url']],                       # 主图只有 1 张
        [sku['sku_img'] for sku in item['sku_list']],
        re.findall(r'<img src="([^"]+)', item['desc'])  # 详情图藏在 HTML
    ]
    for folder, urls in zip(folders, img_lists):
        download_to(folder, urls)

小技巧

主图 pic_url 默认 800×800，把域名 img.1688.com 替换成 img.alicdn.com/imgextra/i4 再拼 _800x800.jpg 可拿更高分辨率。
SKU 图有时为空，前端会 fallback 到主图，自己落地时记得判空，否则同一张图存 N 份。
详情图 desc_img 字段 2025 年下半年已下线，必须解析 desc 里的 HTML，正则别忘了匹配 //img 这种无协议头地址。

四、完整实战：从商品 ID → 落库 SKU+主图

下面这段代码可直接跑通（基于第三方网关，已封装 sign），演示"拿数据 → 解析 SKU → 批量下图片"最简链路：

python 复制代码

import requests, os, re, json
from hashlib import md5

APP_KEY = '你的 AppKey'
APP_SECRET = '你的 AppSecret'
NUM_IID = '610947572360'          # 替换你想抓的商品
BASE_URL = 'https://api-gw.onebound.cn/1688/item_get/'

# 1. 拼参 + 签名
params = {
    'key': APP_KEY,
    'secret': APP_SECRET,
    'num_iid': NUM_IID,
    'cache': 'yes',
    'result_type': 'json',
    'lang': 'cn'
}
sign_str = APP_SECRET + ''.join([f'{k}{v}' for k, v in sorted(params.items())]) + APP_SECRET
params['sign'] = md5(sign_str.encode()).hexdigest().upper()

# 2. 调接口
res = requests.get(BASE_URL, params=params)
data = res.json()['item_get_response']['item']

# 3. 解析 SKU
skus = [
    {
        'sku_id': s['sku_id'],
        'spec': s['sku_spec'],
        'price': float(s['sku_price']),
        'stock': int(s.get('sku_stock', 0))
    }
    for s in data.get('sku_list', [])
]

# 4. 抓图
def save_img(url, path):
    if not url: return
    url = url if url.startswith('http') else 'https:' + url
    os.makedirs(os.path.dirname(path), exist_ok=True)
    with open(path, 'wb') as f:
        f.write(requests.get(url).content)

save_img(data['pic_url'], f'./{NUM_IID}/主图.jpg')
for s in data.get('sku_list', []):
    save_img(s.get('sku_img'), f'./{NUM_IID}/SKU/{s["sku_id"]}.jpg')

# 5. 详情图
detail_imgs = re.findall(r'src="([^"]+)"', data.get('desc', ''))
for idx, url in enumerate(detail_imgs):
    save_img(url, f'./{NUM_IID}/详情/{idx}.jpg')

print('SKU 列表：', json.dumps(skus, ensure_ascii=False))

五、高频踩坑清单

坑点	现象	解决方案
签名 401	官方提示 sign error	1688 签名顺序按参数 Key 升序，最后前后各拼一次 APP_SECRET
阶梯价缺失	SKU 里只有单件价	再调 `alibaba.cpsMedia.productInfo` 拿 `priceRange` 字段
详情图 403	30 天后全挂	落盘时把 `//img` 协议头补全，并做 30 天定时刷新
QPS 被限	连续 200 ms 调一次就 500	默认 1 QPS，批量请加 ≥1 s 延迟，或申请企业配额
sku_stock=0	商品页却显示现货	以 `available_stock` 为准，部分商家设置"展示库存"与"可售库存"双轨

六、小结

SKU 数据一定要做"单位/空值/阶梯价"三重校验，否则前端一上架就会出"下单提示价格已过期"的尴尬。
主图、SKU 图、详情图链接 30 天失效，落盘+回源策略是生产级必备。
1688 的 B2B 属性决定了"起批量、供应商类型、箱规"这些字段和淘宝完全不同，解析逻辑要单独维护，不能复用零售那套模板。

把上面这段代码和清单吃透，基本就能在 1 小时内搭起"SKU+主图"的自动化流水线，后续无论是做选品库、ERP 还是铺货 SaaS，都可直接复用。祝各位调试顺利，永不 403！