raw.douyin.goods_search

抖音商品搜索

实时Beta

GEThttps://api.qovia.ai/v1/raw/douyin/goods_search

按关键词搜索抖音电商的商品（按抖音的原样 JSON 返回）：promotions 商品列表（商品 ID、推广 ID、标题、主图、详情链接、类目），summary_promotions 商品详情卡片（月销量、好评率、到手价、佣金、店铺名称和评分、标签），以及 total 总数、has_more 是否还有下一页和 extra 里的 search_id。page 从 1 开始，每页约 30 条；翻页时把上一页 extra 里的 search_id 作为 search_id 传回，has_more 为 false 时停止。一般 4 秒左右返回。只对有数据的结果计费，没有搜到商品或出错都不计费。

常见用途：选题和热点追踪、关键词监测、跟进竞品动态。

价格: $0.02536 / 次$25.36 / 千次 · 固定价格
计费: 成功且有结果才扣费扣费写在 meta.charged_usd
权限: raw:douyinAPI Key 需要这个 scope
限速: 仅账户限流账户每分钟上限

请求参数

作为查询参数发送

只接受下列参数，多出的参数会返回 400。

keywordstring必填

搜索关键词

最多 100 字

示例口红

pageinteger

页码，从 1 开始；has_more 为 false 时停止

默认1范围1–50

search_idstring

翻页用：上一页返回 extra.search_id，原样传回；第一页不传

最多 512 字格式^[0-9A-Za-z_-]+$

curl 'https://api.qovia.ai/v1/raw/douyin/goods_search?keyword=%E5%8F%A3%E7%BA%A2' \
  -H "Authorization: Bearer $QOVIA_KEY"

把 $QOVIA_KEY 换成你的 API Key

示例响应200 OK

{
  "request_id": "00000000-0000-0000-0000-000000000000",
  "data": {
    "promotions": [
      {
        "product_id": "3633772266610903778",
        "promotion_id": "3641755479459406882",
        "base_info": {
          "title": "【品牌正品】米之莲奢感不沾杯口红哑光雾面持妆显白不易掉色提升气色学生",
          "price": null,
          "main_img": {
            "uri": "ecom-shop-material/png_m_64c4308812882e5da75c2f9146d31af2_sx_192360_www800-800",
            "url_list": [
              "https://p3-aio.ecombdimg.com/obj/ecom-shop-material/png_m_64c4308812882e5da75c2f9146d31af2_sx_192360_www800-800"
            ]
          },
          "detail_url": "https://haohuo.jinritemai.com/ecommerce/trade/detail/index.html?id=3633772266610903778&origin_type=2631",
          "category": {
            "first_category": {
              "category_id": 1000002395,
              "category_name": "彩妆香水"
            },
            "second_category": {
              "category_id": 1000002412,
              "category_name": "唇部彩妆"
            },
            "third_category": {
              "category_id": 1000002526,
              "category_name": "有色唇膏/口红"
            },
            "fourth_category": {
              "category_id": 0,
              "category_name": ""
            },
            "leaf_layer": 3
          }
        }
      }
    ],
    "has_more": true,
    "total": 500,
    "extra": {
      "channel_id": "200",
      "recall_type": "Search",
      "search_id": "9693f4b04995e774b8d36aca1ae771d3..."
    },
    "summary_promotions": [
      {
        "product_id": "3633772266610903778",
        "promotion_id": "3641755479459406882",
        "base_model": {
          "product_info": {
            "name": "【品牌正品】米之莲奢感不沾杯口红哑光雾面持妆显白不易掉色提升气色学生",
            "detail_url": "https://haohuo.jinritemai.com/ecommerce/trade/detail/index.html?id=3633772266610903778&origin_type=2631",
            "month_sale": {
              "origin": 1669
            },
            "good_ratio": {
              "origin": 94.79961832061069,
              "integer": "94",
              "decimal": "8",
              "suffix": "%"
            }
          },
          "marketing_info": {
            "price_desc": {
              "price": {
                "origin": 2990,
                "integer": "29",
                "decimal": "9",
                "suffix": ""
              },
              "price_text": "到手价"
            }
          },
          "shop_info": {
            "shop_id": 113503652,
            "shop_name": "喵妮美妆严选"
          }
        }
      }
    ]
  },
  "meta": {
    "billed": true,
    "charged_usd": "0.025360",
    "balance_usd": "9.974640",
    "empty": false
  }
}

目录示例，不是实时数据

响应

成功返回 HTTP 200 和统一信封：request_id、data（本接口的数据，见示例）、meta（扣费信息）。结果为空时同样是 200，meta.empty 为 true，不扣费，data 可能为空结构或 null。

响应结构详解

错误码

这个接口可能返回的错误码
code	HTTP	计费	说明
`scope_denied`	403	不扣费	这个 API Key 没有该接口需要的权限（scope）。
`endpoint_unavailable`	503	不扣费	接口暂不可用（尚未接入数据源，或价格未配置），没有执行。
`invalid_params`	400	不扣费	参数没有通过校验：缺少必填、类型或格式不对、数组超过允许的条数、有多余参数，或 POST 请求体不是 JSON 对象。单个参数的错误以参数名开头（`item_id: …`），缺少必填或多出参数以 `params: …` 开头。
`rate_limited`可重试	429	不扣费	超过账户每分钟请求上限（滑动 60 秒窗口），按 `Retry-After` 等待。
`too_many_unbilled`可重试	429	不扣费	最近 10 分钟打到数据源的请求里，空结果、不存在或被拒的有至少 50 次且占 80% 以上，放慢后再试。
`insufficient_balance`	402	不扣费	余额不足以支付这次调用，请先充值。
`upstream_busy`可重试	503	已退款	数据源繁忙或在冷却，已退款，按 `Retry-After` 重试。
`upstream_timeout`	504	已退款	数据源超时，已退款。
`upstream_error`	502 / 503	已退款	数据源返回失败，已退款。
`upstream_rejected`	400	已退款	数据源拒绝了这组参数（格式合法但不被接受），已退款。
`not_found`	404	已退款	数据源里没有这条数据（已删除或 ID 不存在），已退款。
`reservation_expired`	504	已退款	处理时间过长，已自动退款，没有返回数据。

任何请求还可能返回认证错误：401 invalid_api_key、403 account_disabled、429 too_many_auth_failures。

全部错误码

在浏览器里直接调用

需要登录并充值；调试台调用和 API 调用一样计费。

在调试台试用创建 API Key

请求参数

响应

错误码

抖音的其他接口