# 速卖通 商品变体 API (aliexpress.variants)

- Canonical page: https://everyinfra.com/aliexpress-api/product_detail
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "aliexpress", "action": "variants", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: single object
- Related: Same parameters and fields as aliexpress.product_detail, but returns a result only when the product has a SKU variant list; a product without one counts as an empty result and is not charged.
- Mode: sync; add "mode": "async" for slow tasks

## Health

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

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| url | not declared | yes | not declared | AliExpress 商品链接，建议传 https://www.aliexpress.com/item/<商品ID>.html。profile 返回商品资料而非用户主页，variants 查商品变体，reviews / ratings 查评论或评分汇总；product_detail 也接收纯数字商品 ID。 |
| country | not declared | no | not declared | product_detail 查询的国家/地区代码，例如 US；默认 US，并转换为大写。它选择商品查询地区，不会修改你的账户国家或实际下单收货地址。 |
| currency | not declared | no | not declared | product_detail 商品价格的展示币种，例如 USD；默认 USD，并转换为大写。与 EveryInfra API 的调用计费币种无关。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| url | 该记录在原平台上的可访问链接。 |
| name | 名称。用于账号/商品/商家类能力，指该对象本身的名字。 |
| text | 正文内容，已去除 HTML 标签，全文返回、不截断（个别平台的列表结果本身只有摘要，以该平台的字段说明为准）。 |
| price | 价格数值，不含货币符号；币种见 currency。 |
| original_price | 原价（划线价）。与 price 对比可算真实折扣。 |
| currency | 价格币种代码（如 CNY、USD）。price 存在但 currency 为 null 时不要假定币种。 |
| discount | 折扣力度。 |
| sold_count | 销量。 |
| rating | 评分。**分制随平台而异**，同一行的 `rating_scale` 给出该平台满分 (多数是 5，Booking/豆瓣/爱奇艺/NAVER 是 10)。跨平台比较前必须先按 rating_scale 换算。直接比数字会得出反的结论。 |
| rating_scale | 上一列 `rating` 的满分。5 表示五星制、10 表示十分制。只在该行有 rating 时出现。 |
| review_count | 评价条数，用于商品/商家类能力。null 表示不公开，不等于 0。 |
| shipping | 运费与配送方式。 |
| variants | 规格（SKU）列表，每项一个规格：sku_id、properties（规格名 → 取值，如 Color、Size）、price、original_price、stock、available、image_url、max_buy_count；平台没给的项不出现。 |
| store_name | 店铺名称。 |
| store_url | 店铺链接。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| images | 图片链接：商品类能力里是商品轮播图（按商品页顺序），reviews 里是买家晒图。 |
| description_images | 商品描述区图片，来自受限的 AliExpress 媒体正文地址。 |
| price_max | 价格区间上限（多规格商品）。 |
| original_price_max | 原价区间上限（多规格商品）。 |
| sold_text | 销量原文（如「10,000+ sold」）；是平台展示的约数，不是精确销量。 |
| attributes | 商品属性列表（材质、型号等 {name, value} 行）。 |
| category_id | 分类 ID。 |
| category_path | 分类路径。 |
| ship_to | 这次报价与运费对应的收货国家/地区。 |
| total_stock | 商品总库存（各规格合计；单个规格的库存在 variants 每项的 stock）。 |
| video_url | 商品视频链接。 |
| store_id | 店铺 ID。 |
| seller_id | 卖家 ID（速卖通自己的公开 ID）。 |
| store_country | 店铺所在国家/地区。 |
| store_opened_at | 店铺开设时间。**新店 + 高销量是刷单的常见组合。** |
| store_positive_rate | 店铺好评率原文（如 95.2%）。 |
| store_rating | 店铺评分。 |
| store_sold_180d | 店铺近 180 天销量原文。 |
| store_is_top_rated | 店铺是否为平台优质卖家（Top Rated）。 |
| 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": "aliexpress",
  "action": "variants",
  "params": {
    "url": "https://www.aliexpress.com/item/3256806025886958.html"
  }
}'
```

```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": "aliexpress",
        "action": "variants",
        "params": {
            "url": "https://www.aliexpress.com/item/3256806025886958.html",
        },
    },
    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": "aliexpress",
  "action": "variants",
  "results": {
    "id": "•••",
    "url": "https://www.aliexpress.com/item/3256806025886958.html",
    "name": "Thermal Underwear Tops Men Spring Clothes Thermal Shirt Autumn Men's Winter Tights High Neck Thin Slim Fit Long Sleeve T-shirt",
    "price": 1.91,
    "original_price": 11.06,
    "currency": "USD",
    "discount": 83,
    "rating": 4.4,
    "review_count": 404,
    "shipping": [
      {
        "method": "AliExpress Selection Standard Shipping",
        "free_shipping": false,
        "ship_from": "China",
        "ship_to": "US",
        "delivery_days_min": 8,
        "delivery_days_max": 13,
        "estimated_delivery": "Nov. 01 – Nov. 06",
        "tracking": true
      }
    ],
    "variants": [
      {
        "sku_id": "12000036301240276",
        "properties": {
          "Color": "Dark Grey",
          "Size": "S"
        },
        "price": 2.23,
        "original_price": 11.78,
        "stock": 6,
        "available": true,
        "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/Sd1b109e7315a4b0bb6a0e676dbe81f11N.jpg",
        "max_buy_count": 1
      },
      {
        "sku_id": "12000036301240277",
        "properties": {
          "Color": "Dark Grey",
          "Size": "M"
        },
        "price": 2.43,
        "original_price": 12.22,
        "stock": 3,
        "available": true,
        "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/Sd1b109e7315a4b0bb6a0e676dbe81f11N.jpg",
        "max_buy_count": 1
      },
      {
        "sku_id": "12000036301240278",
        "properties": {
          "Color": "Dark Grey",
          "Size": "L"
        },
        "price": 2.21,
        "original_price": 11.74,
        "stock": 0,
        "available": false,
        "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/Sd1b109e7315a4b0bb6a0e676dbe81f11N.jpg",
        "max_buy_count": 0
      }
    ],
    "store_name": "Shop1102888504 Store",
    "store_url": "https://www.aliexpress.com/store/1102892506",
    "image_url": "https://ae-pic-a1.aliexpress-media.com/kf/S702341bd952e48d19070fda1b1b2c15eI.jpg",
    "images": [
      "https://ae-pic-a1.aliexpress-media.com/kf/S702341bd952e48d19070fda1b1b2c15eI.jpg",
      "https://ae-pic-a1.aliexpress-media.com/kf/S2259b7a7b87445c484e782f739f76593E.jpg",
      "https://ae-pic-a1.aliexpress-media.com/kf/S6e96c6eeaa8b44d3bd0189288bd92471o.jpg"
    ],
    "price_max": 3.15,
    "original_price_max": 13.84,
    "sold_text": "2,000+ sold",
    "attributes": [
      {
        "name": "Special Features",
        "value": "Lightweight"
      },
      {
        "name": "Product Care Instructions",
        "value": "Dry Clean Only"
      },
      {
        "name": "Closure Type",
        "value": "Pull On"
      }
    ],
    "category_id": "200000783",
    "category_path": "•••/•••/•••",
    "ship_to": "US",
    "total_stock": 96,
    "video_url": "https://video.aliexpress-media.com/play/u/ae_sg_item/2215998649727/p/1/e/6/t/10301/5000232324880.mp4",
    "store_id": "1102892506",
    "seller_id": "•••",
    "store_country": "China",
    "store_opened_at": "2023-06-12 01:35:24",
    "store_positive_rate": "93.9%",
    "store_sold_180d": "20,000+",
    "store_is_top_rated": false,
    "platform": "aliexpress",
    "rating_scale": 5
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## Also

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