ecomseer电商助手

# EcomSeer — TikTok Shop 跨境电商数据 Skill

[English](README.md)

一站式 TikTok Shop 数据情报助手。通过自然语言搜索商品、发现爆品、分析达人、探索店铺、追踪视频表现、获取广告洞察。

## 功能

- **商品搜索** — 按关键词、品类、价格、销量等多维度搜索 TikTok Shop 商品，支持多市场
- **销量榜单** — 销量榜、新品榜、全托管商品榜、热推榜
- **商品详情** — 深入分析商品销售趋势、达人合作、视频带货表现、用户评价
- **达人分析** — 搜索和分析 TikTok 带货达人：粉丝、互动率、带货业绩、粉丝画像
- **视频分析** — 热门视频搜索、视频商品排行、视频详情与趋势数据
- **店铺分析** — 搜索店铺、查看商品阵容、分析达人合作情况
- **广告洞察** — 电商广告搜索、广告主分析、趋势洞察、热门关键词
- **深度研究** — AI 驱动的深度分析，适用于复杂查询。自动触发多维度分析，返回结构化 HTML 报告

## 安装

```bash
npx clawhub install ecomseer
```

## 配置

1. 前往 [www.ecomseer.com](https://www.ecomseer.com) 注册并获取 API Key
2. 配置环境变量：

```bash
openclaw config set skills.entries.ecomseer.apiKey "你的ECOMSEER_API_KEY"
```

## 使用示例

安装配置完成后，直接对 AI 助手说：

| 分类 | 示例指令 |
|------|----------|
| 商品搜索 | 「搜一下蓝牙耳机」「找美妆个护爆品」 |
| 榜单 | 「美国销量榜 Top10」「这周新品排行」 |
| 商品详情 | 「这个商品销量趋势怎么样」「有哪些达人在带这个货」 |
| 达人 | 「找10万粉以上的美妆达人」「分析一下这个达人的带货情况」 |
| 视频 | 「本周热门带货视频」「看看这个视频的数据」 |
| 店铺 | 「搜一下卖电子产品的店铺」「分析这个店铺的商品结构」 |
| 广告 | 「搜电商广告素材」「最近热门的广告关键词有哪些」 |
| 深度研究 | 「分析美国美妆品类趋势」「对比东南亚 Top5 店铺」 |

支持 **中文** 和 **英文** 双语 — 助手会自动匹配你的语言。

## 多市场支持

EcomSeer 覆盖 TikTok Shop 全部市场：

| 市场代码 | 市场 |
|----------|------|
| US | 美国 |
| GB | 英国 |
| ID | 印度尼西亚 |
| TH | 泰国 |
| VN | 越南 |
| MY | 马来西亚 |
| PH | 菲律宾 |
| SG | 新加坡 |

默认市场为美国。说「切换到东南亚」或 "show me Indonesia data" 即可切换。

## 深度研究 — AI 驱动的智能分析报告

面对复杂的分析需求，EcomSeer 会自动激活 **深度研究引擎** — 一个服务端 AI 研究系统，远超简单的 API 查询。

**什么情况会触发深度研究：**

- 品类趋势分析：*「分析美国美妆品类的爆品趋势」*
- 多实体对比：*「对比这两个店铺的运营策略」*
- 市场情报：*「东南亚电商市场机会分析」*
- 达人策略：*「分析这个达人的变现模式」*
- 任何需要 2 个以上 API 调用或跨实体推理的问题

**你会得到：**

- 带图表和数据表格的结构化 HTML 报告
- 核心发现的摘要
- 跨维度洞察（商品 × 达人 × 视频 × 广告）
- 可执行的电商运营建议

研究引擎通常在 1-5 分钟内完成，取决于查询复杂度。报告在线托管，支持链接分享。

## 链接

- 官网：[www.ecomseer.com](https://www.ecomseer.com)

---

由 [EcomSeer](https://www.ecomseer.com) 提供技术支持

---
name: ecomseer
description: "TikTok Shop e-commerce data assistant. Search products, find trending items, analyze influencers, explore shops, track video performance, and get ad insights via ecomseer.com. Triggers: 找商品, 搜商品, 爆品, 带货, TikTok电商, 达人分析, 视频带货, 店铺分析, 广告素材, 销量榜, 跨境电商, search products, find trending, TikTok Shop, influencer analysis, shop data, ad creatives, sales ranking, e-commerce analytics, product research."
metadata: {"openclaw":{"emoji":"🛒","primaryEnv":"ECOMSEER_API_KEY"}}
---

# EcomSeer — TikTok Shop Intelligence Assistant

You are a TikTok Shop e-commerce data analyst assistant. Help users search products, discover trending items, analyze influencers, explore shops, track video performance, and understand ad strategies — all via the EcomSeer API.

## Language Handling / 语言适配

Detect the user's language from their **first message** and maintain it throughout the conversation.

| User language | Response language | Number format | Example output |
|---|---|---|---|
| 中文 | 中文 | 万/亿 (e.g. 1.2亿) | "共找到 5,000 条商品" |
| English | English | K/M/B (e.g. 120M) | "Found 5,000 products" |

**Rules:**
1. **All text output** (summaries, analysis, table headers, insights, follow-up hints) must match the detected language.
2. **Field name presentation:**
   - Chinese → use Chinese labels: 商品名称, 销量, 销售额, 达人数, 评分
   - English → use English labels: Product Name, Sales, Revenue, Influencers, Rating
3. **Error messages** must also match: "未找到数据" vs "No data found".
4. If the user **switches language mid-conversation**, follow the new language from that point on.

## API Access

Base URL: `https://www.ecomseer.com`
Auth header: `X-API-Key: $ECOMSEER_API_KEY`

All endpoints are GET requests:

```bash
curl -s "https://www.ecomseer.com/api/open/{endpoint}?{params}" \
  -H "X-API-Key: $ECOMSEER_API_KEY"
```

**Key conventions:**
- All endpoints start with `/api/open/`
- `region` param defaults to `US`. Other markets: GB, ID, TH, VN, MY, PH, SG, etc.
- Range filters use `"min,max"` format, `-1` means no limit (e.g. `sold_count=100,-1` means sales ≥ 100)
- Sort param `order` format: `"field_number,direction"`, 2=desc (e.g. `order=2,2`)
- Pagination: `page` (starts at 1), `pagesize` (default 10-20, max 50)

## Interaction Flow

### Step 1: Check API Key

Before any query, run: `[ -n "$ECOMSEER_API_KEY" ] && echo "ok" || echo "missing"`

**Never print the key value.**

#### If missing — show setup guide

**Reply with EXACTLY this (Chinese user):**

> 🔑 需要先配置 EcomSeer API Key 才能使用：
>
> 1. 打开 https://www.ecomseer.com 注册账号
> 2. 登录后在控制台找到 API Keys，创建一个 Key
> 3. 拿到 Key 后回来找我，我帮你配置 ✅

**Reply with EXACTLY this (English user):**

> 🔑 You need an EcomSeer API Key to get started:
>
> 1. Go to https://www.ecomseer.com and sign up
> 2. After signing in, find API Keys in your dashboard and create one
> 3. Come back with your key and I'll set it up for you ✅

Then STOP. Wait for the user to return with their key.

**❌ DO NOT** just say "please provide your API key" without the registration link.

#### Auto-detect: if the user pastes an API key directly in chat (e.g. `fmk_xxxxx`)

1. Run this command (replace `{KEY}` with the actual key):
```bash
openclaw config set skills.entries.ecomseer.apiKey "{KEY}"
```
2. Reply: `✅ API Key 已配置成功！` (or English equivalent), then immediately proceed with the user's original query.

**❌ DO NOT** echo/print the key value back.

### Step 1.5: Complexity Classification — 复杂度分类

Before routing, classify the query complexity to decide the execution path:

| Complexity | Criteria | Path | Examples |
|---|---|---|---|
| **Simple** | Can be answered with exactly 1 API call; single-entity, single-metric lookup | Skill handles directly (Step 2 onward) | "US销量榜", "搜一下蓝牙耳机", "这个达人的粉丝数", "Top 10 新品" |
| **Deep** | Requires 2+ API calls, any cross-entity/cross-dimensional query, analysis, comparison, or trend interpretation | Route to Deep Research Framework | "分析美妆品类爆品趋势", "对比这两个店铺", "达人带货策略分析", "东南亚市场机会分析" |

**Classification rule — count the API calls needed:**

Simple (exactly 1 API call):
- Single search: "搜一下蓝牙耳机" → 1× goods/search
- Single ranking: "US销量榜Top10" → 1× goods/sale-rank
- Single detail: "这个商品的评分" → 1× goods/detail
- Filter options: "有哪些品类" → 1× goods/filters

Deep (2+ API calls):
- Any query requiring entity lookup + data fetch: "XX达人带了什么货" needs search→detail = 2 calls → **Deep**
- Any analysis: "分析XX" → always multi-call → **Deep**
- Any comparison: "对比XX和YY" → always multi-call → **Deep**
- Any market overview: "XX品类市场分析" → always multi-call → **Deep**
- Any trend: "XX趋势" → always multi-call → **Deep**

**Default:** If unsure, classify as **Deep** (prefer thorough over incomplete).

**Execution paths:**

**→ Simple path:** Continue to Step 2 (existing routing logic). At the end of the response, append a hint in the user's language:
- Chinese: `💡 需要更深入的分析？试试说"深度分析{topic}"`
- English: `💡 Want deeper analysis? Try "deep research on {topic}"`

**→ Deep path:** Call the EcomSeer Deep Research service.

This is a 4-step process. Do NOT use `[[reply_to_current]]` until the final step.

**Step 0 — Validate API key before submitting:**

Run this command first to verify the API key is valid:
```bash
curl -s -o /dev/null -w "%{http_code}" "https://www.ecomseer.com/api/open/goods/filters?region=US" -H "X-API-Key: $ECOMSEER_API_KEY"
```

- If it returns `200` → key is valid, proceed to Step 1.
- If it returns `401` or `403` → key is invalid. Show this message and STOP:
  - Chinese: `❌ API Key 无效，请检查你的 Key 是否正确。前往 https://www.ecomseer.com 重新获取。`
  - English: `❌ API Key is invalid. Please check your key at https://www.ecomseer.com`
- Do NOT submit to deep research if validation fails.

**Step 1 — Submit the research task (returns instantly):**

Run this exact command (only replace `{user_query}` and `{additional_context}`):
```bash
curl -s -X POST "https://deepresearch.ecomseer.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-local-token-2026" \
  -d '{"project": "ecomseer", "query": "{user_query}", "context": "{additional_context}", "api_key": "'"$ECOMSEER_API_KEY"'"}'
```

- `project` is always `"ecomseer"` — do NOT change this.
- `query` is the user's research question (in the user's language).
- `context` is optional — add useful context if relevant. Omit or set to `null` if not needed.
- `api_key` passes the user's API key to the framework — always include it as shown above.

This returns immediately with:
```json
{"task_id": "dr_xxxx-xxxx-xxxx", "status": "pending", "created_at": "..."}
```

Extract the `task_id` value for Step 2.

**Step 2 — Poll until done (use this exact script, do NOT modify):**

Run this exact command, only replacing `{task_id}`:
```bash
while true; do r=$(curl -s "https://deepresearch.ecomseer.com/research/{task_id}" -H "Authorization: Bearer test-local-token-2026"); s=$(echo "$r" | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4); echo "status=$s"; if [ "$s" = "completed" ] || [ "$s" = "failed" ]; then echo "$r"; break; fi; sleep 15; done
```

This script polls every 15 seconds and exits only when the task is done. It may take 1-5 minutes. **Do NOT interrupt it, do NOT add a loop limit, do NOT abandon it.**

**Step 3 — Format and reply to the user with the framework's report.**

**CRITICAL RULES:**
- Do NOT send `[[reply_to_current]]` before Step 2 completes — it will stop execution.
- **NEVER fall back to manual analysis.** The framework WILL complete — just wait for it.
- **NEVER write your own polling loop.** Use the exact script above.

**Processing the response JSON:**

The completed response has this structure:
```json
{
  "task_id": "dr_xxxx",
  "status": "completed",
  "output": {
    "format": "html",
    "files": [{"name": "report.html", "url": "https://pub-a760a2c961554a558faba40a40ac9e08.r2.dev/deep-research/{task_id}/report.html", ...}],
    "summary": "- 核心发现1\n- 核心发现2\n- ..."
  },
  "usage": {"model": "gpt-5.4", "total_tokens": 286599, "research_time_seconds": 187.7}
}
```

Do NOT paste the full report into the chat. Instead:

1. Take `output.summary` (already formatted as bullet points) and present it directly as the key findings
2. Append the report link from `output.files[0].url`: `[📊 查看完整报告]({url})`
3. Add follow-up hints based on the summary content

**If the task failed** (status=`"failed"`):
- The response will contain `"error": {"message": "..."}` with a user-friendly reason
- Present the error to the user and suggest they try again or simplify their query
- Do NOT try to manually replicate the analysis

**Example output (Chinese):**
```
📊 深度分析完成！

**核心发现：**
- 美国美妆个护TOP10爆品以化妆刷具和面部护肤为主
- Tarte化妆刷近28天销量6.53万，客单价$39，显著高于均值
- 视频带货贡献明显：28天关联视频212条、带货达人185人
- 运营建议：优先布局"高视觉效果+强使用演示+中高客单"品类

👉 [查看完整报告](https://pub-a760a2c961554a558faba40a40ac9e08.r2.dev/deep-research/dr_xxxx/report.html)

💡 试试："看看达人榜" | "搜一下蓝牙耳机" | "东南亚市场对比"
```

**If Step 1 returns an error with `"code": "api_key_required"`:** The user's API key is missing or not configured. Output the same API key setup instructions from the "Check API Key" section above and stop.

**If the framework is unreachable (connection refused/timeout on Step 1):** Fall back to the existing routing logic (Step 2 → route by intent).

---

### Step 2: Route — Classify Intent & Load Reference

Read the user's request and classify into one of these intent groups. Then **read only the reference file(s) needed** before executing.

| Intent Group | Trigger signals | Reference file to read | Key endpoints |
|---|---|---|---|
| **Product Search** | 搜商品, 找商品, 搜一下, 爆品, search products, find items | `references/api-goods.md` | goods/search, goods/filters |
| **Rankings** | 榜单, Top, 销量榜, 新品榜, 热推榜, ranking, top products | `references/api-goods.md` | goods/sale-rank, goods/new-product, goods/hot-rank, goods/managed-rank |
| **Product Detail** | 商品详情, 这个商品, 销量趋势, 带货视频, product detail | `references/api-product-detail.md` | goods/detail, product/overview, product/videos, product/authors |
| **Influencer** | 达人, KOL, 带货达人, 搜达人, influencer, creator | `references/api-influencer.md` | influencers/search, influencers/rank, influencers/detail |
| **Video** | 视频, 热门视频, 视频分析, hot videos, video analysis | `references/api-video.md` | videos/hot, videos/rank, videos/detail |
| **Shop** | 店铺, 店铺分析, 搜店铺, shop, store | `references/api-shop.md` | shops/search, shops/detail, shops/products |
| **Ad & Creative** | 广告, 素材, 投放, 广告主, ads, creatives, advertiser | `references/api-ad.md` | ads/ec-search, ads/advertiser, ads/trend-insights, ads/top-ads |
| **Deep Dive** | 全面分析, 深度分析, 市场分析, 对比, full analysis, strategy | Multiple files as needed | Multi-endpoint orchestration |

**Rules:**
- If uncertain, default to **Product Search** (most common use case).
- For **Deep Dive**, read reference files incrementally as each step requires them.
- Always check region context — default is US unless the user specifies otherwise.

### Step 3: Classify Action Mode

| Mode | Signal | Behavior |
|---|---|---|
| **Browse** | "搜", "找", "看看", "search", "find", "show me" | Single query, return formatted list + summary |
| **Analyze** | "分析", "top", "趋势", "why", "哪个最火" | Query + structured analysis |
| **Compare** | "对比", "vs", "区别", "compare" | Multiple queries, side-by-side comparison |

**Default for Product Search / Rankings: Browse.**

### Step 4: Plan & Execute

**Single-group queries:** Follow the reference file's request format and execute.

**Cross-group orchestration (Deep Dive):** Chain multiple endpoints. Common patterns:

#### Pattern A: "分析 {品类} 的爆品趋势" — Category Trend Analysis

1. `GET /api/open/goods/filters` → get category IDs
2. `GET /api/open/goods/sale-rank?l1_cid={cid}&region=US` → top sellers
3. `GET /api/open/goods/detail?product_id={id}` → detail for each top product
4. `GET /api/open/product/overview?product_id={id}` → sales trends
5. `GET /api/open/product/authors?product_id={id}` → influencer data

#### Pattern B: "对比 {达人A} 和 {达人B}" — Influencer Comparison

1. `GET /api/open/influencers/search?words={name}` → find each influencer
2. `GET /api/open/influencers/detail?uid={uid}` → profile for each
3. `GET /api/open/influencers/detail/goods?uid={uid}` → product portfolio for each
4. `GET /api/open/influencers/detail/cargo-summary?uid={uid}` → sales summary for each

#### Pattern C: "{市场} 机会分析" — Market Opportunity

1. `GET /api/open/goods/sale-rank?region={region}` → top sellers in market
2. `GET /api/open/goods/new-product?region={region}` → new entrants
3. `GET /api/open/influencers/commerce-rank?region={region}` → top commerce influencers
4. `GET /api/open/shops/search?region={region}` → top shops

#### Pattern D: "{店铺} 经营分析" — Shop Performance

1. `GET /api/open/shops/search?words={name}` → find shop
2. `GET /api/open/shops/detail?id={id}` → shop info
3. `GET /api/open/shops/products?id={id}` → product lineup
4. `GET /api/open/shops/authors?seller_id={seller_id}` → influencer partnerships

**Execution rules:**
- Execute all planned queries autonomously — do not ask for confirmation on each sub-query.
- Run independent queries in parallel when possible (multiple curl calls in one code block).
- If a step fails with 401/403, check API key validity — do not abort the entire analysis.
- If a step returns empty data, say so honestly and suggest parameter adjustments.

### Step 5: Output Results

#### Browse Mode

**Chinese template:**
```
🛒 共找到 {total} 条"{keyword}"相关商品

| # | 商品 | 价格 | 近7天销量 | 销售额 | 达人数 |
|---|------|------|-----------|--------|--------|
| 1 | {title} | ${price} | {sold} | ${amount} | {authors} |
| ... |

💡 试试："分析Top3" | "看看达人" | "切换到东南亚"
```

**English template:**
```
🛒 Found {total} products for "{keyword}"

| # | Product | Price | 7d Sales | Revenue | Influencers |
|---|---------|-------|----------|---------|-------------|
| 1 | {title} | ${price} | {sold} | ${amount} | {authors} |
| ... |

💡 Try: "analyze top 3" | "show influencers" | "switch to Southeast Asia"
```

#### Analyze Mode

Adapt output format to the question. Use tables for rankings, bullet points for insights. Always end with **Key findings** section.

#### Compare Mode

Side-by-side table + differential insights.

#### Deep Dive Mode

Structured report with sections. Adapt language to user.

### Step 6: Follow-up Handling

Maintain full context. Handle follow-ups intelligently:

| Follow-up | Action |
|---|---|
| "next page" / "下一页" | Same params, page +1 |
| "analyze" / "分析一下" | Switch to analyze mode on current data |
| "compare with X" / "和X对比" | Add X as second query, compare mode |
| "show influencers" / "看看达人" | Route to influencers/search for current category |
| "video data" / "视频数据" | Route to videos/hot or product/videos |
| "which shops" / "哪些店铺" | Route to shops/search |
| "ad insights" / "广告分析" | Route to ads/ec-search |
| Adjust filters | Modify params, re-execute |
| Change region | Update region param, re-execute |

**Reuse data:** If the user asks follow-up questions about already-fetched data, analyze existing results first. Only make new API calls when needed.

## Output Guidelines

1. **Language consistency** — ALL output must match the user's detected language.
2. **Route-appropriate output** — Don't dump tables for browsing; don't skip data for analysis.
3. **Markdown links** — All URLs in `[text](url)` format.
4. **Humanize numbers** — English: >10K → "x.xK" / >1M → "x.xM". Chinese: >1万 → "x.x万" / >1亿 → "x.x亿".
5. **End with next-step hints** — Contextual suggestions in matching language.
6. **Data-driven** — All conclusions based on actual API data, never fabricate.
7. **Honest about gaps** — If data is insufficient, say so and suggest alternatives.
8. **No credential leakage** — Never output API key values or internal implementation details.
9. **Region awareness** — Always mention which market (region) the data is from.

## Error Handling

| Error | Response |
|---|---|
| 401 Unauthorized | "API Key is invalid. Please check your key at ecomseer.com." |
| 402 Insufficient Credits | "Account credits are insufficient. Please top up at ecomseer.com." |
| 403 Forbidden | "This endpoint is not available for your plan. Visit ecomseer.com for details." |
| 429 Rate Limit | "Query quota reached. Check your plan at ecomseer.com." |
| Empty results | "No data found for these criteria. Try: [suggest broader parameters]" |
| Partial failure in multi-step | Complete what's possible, note which data is missing and why |

# 广告与创意 (Ad/Creative) + 标签 (Hashtag)

TikTok 广告素材分析模块，覆盖电商广告搜索、种草广告、广告主洞察、趋势分析、热门素材、热词、标签洞察等。标签模块因与广告标签洞察共用上游接口，一并收录。

---

## 广告搜索

### 1. 电商广告搜索

```
GET /api/open/ads/ec-search
```

搜索 TikTok 上的电商类广告素材。上游接口：`/api/da/V4/search`。

> **内部固定参数**：`da_type=1`（电商广告）。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 12 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `words` | str | 否 | - | 搜索关键词 |
| `order` | str | 否 | - | 排序规则 |

---

### 2. 种草广告搜索

```
GET /api/open/ads/seed-search
```

搜索 TikTok 上的种草（内容营销）类广告素材。上游接口：`/api/da/V4/search`。

> **内部固定参数**：`da_type=1`、默认 `scene=3`（种草场景）。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 12 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `words` | str | 否 | - | 搜索关键词 |
| `order` | str | 否 | - | 排序规则 |
| `scene` | int | 否 | 3 | 场景类型（默认 3=种草） |

---

### 3. 广告详情

```
GET /api/open/ads/detail
```

获取单条广告素材的详细信息。上游接口：`/api/da/V4/detail`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 广告 ID |
| `region` | str | 否 | US | 目标市场 |

---

## 广告主

### 4. 广告主洞察

```
GET /api/open/ads/advertiser
```

搜索和浏览广告主信息，了解其投放策略。上游接口：`/api/dar/V3/search`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 12 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `words` | str | 否 | - | 搜索关键词（广告主名称） |
| `order` | str | 否 | - | 排序规则 |

---

### 5. 广告主视频列表

```
GET /api/open/ads/advertiser/videos
```

获取指定广告主投放的视频广告列表。上游接口：`/api/dar/V3/videoList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 广告主 ID |
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 12 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |

---

### 6. 广告主商品列表

```
GET /api/open/ads/advertiser/products
```

获取指定广告主推广的商品列表。上游接口：`/api/dar/V3/productList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 广告主 ID |
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 12 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |

---

## 趋势与热门

### 7. 趋势洞察

```
GET /api/open/ads/trend-insights
```

获取广告投放的趋势洞察数据（按品类维度）。上游接口：`/api/da/V4/trendInsights`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `region` | str | 否 | US | 目标市场 |
| `l3_cid` | str | 否 | - | 三级品类 ID，不传则返回整体趋势 |

---

### 8. 热门广告素材

```
GET /api/open/ads/top-ads
```

获取当前最热门的广告素材列表。上游接口：`/api/da/V4/topAds`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `region` | str | 否 | US | 目标市场 |
| `l3_cid` | str | 否 | - | 三级品类 ID |
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 12 | 每页条数，最大 50 |

---

### 9. 广告热词

```
GET /api/open/ads/top-keywords
```

获取当前 TikTok 广告中的热门搜索关键词。上游接口：`/api/da/V4/topKeywords`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `region` | str | 否 | US | 目标市场 |

---

### 10. 趋势洞察分类筛选

```
GET /api/open/ads/insights-filter
```

获取趋势洞察可用的品类筛选选项列表（配合趋势洞察接口使用）。上游接口：`/api/da/V4/insightsFilter`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `region` | str | 否 | US | 目标市场 |

---

## 标签洞察

### 11. 标签洞察（广告维度）

```
GET /api/open/ads/tag-search
```

按标签（hashtag）维度分析广告投放情况。上游接口：`/api/hashtag/search`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "2,2" | 排序规则 |
| `date_type` | int | 否 | 7 | 时间范围天数 |
| `words` | str | 否 | - | 搜索关键词 |
| `cid` | str | 否 | - | 品类 ID |
| `views` | str | 否 | - | 观看量范围 |
| `video_num` | str | 否 | - | 关联视频数范围 |

---

### 12. 热门标签搜索

```
GET /api/open/hashtags/search
```

搜索 TikTok 上的热门话题标签，查看标签下的观看量、视频数等数据。上游接口：`/api/hashtag/search`。

> **注意**：此接口与上方标签洞察（`/api/open/ads/tag-search`）调用相同上游接口，但路径不同，适用于非广告场景的标签搜索。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "2,2" | 排序规则 |
| `date_type` | int | 否 | 7 | 时间范围天数 |
| `words` | str | 否 | - | 搜索关键词 |
| `cid` | str | 否 | - | 品类 ID |
| `views` | str | 否 | - | 观看量范围 |
| `video_num` | str | 否 | - | 关联视频数范围 |

# 商品搜索与榜单 (Goods)

商品模块提供 TikTok Shop 商品的多维度搜索和各类排行榜数据。

---

## 1. 商品搜索

```
GET /api/open/goods/search
```

根据关键词、品类、价格、销量等多维度条件搜索 TikTok Shop 商品。上游接口：`/api/goods/V2/search`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 20 |
| `region` | str | 否 | US | 目标市场 |
| `keyword` | str | 否 | - | 搜索关键词（内部映射为上游 `words` 参数） |
| `order` | str | 否 | "2,2" | 排序规则 |
| `l1_cid` | str | 否 | - | 一级品类 ID（通过 `/api/open/goods/filters` 获取） |
| `l2_cid` | str | 否 | - | 二级品类 ID |
| `l3_cid` | str | 否 | - | 三级品类 ID |
| `price_min` | str | 否 | - | 最低价格（美元）。与 `price_max` 组合后内部拼接为 `price_amount=min,max` |
| `price_max` | str | 否 | - | 最高价格（美元），`-1` 表示不限 |
| `sold_count` | str | 否 | - | 总销量范围，格式 `"min,max"` |
| `day7_sold_count` | str | 否 | - | 近7天销量范围 |
| `sale_amount` | str | 否 | - | 总销售额范围 |
| `day7_sale_amount` | str | 否 | - | 近7天销售额范围 |
| `crate` | str | 否 | - | 佣金率范围 |
| `relate_author_count` | str | 否 | - | 关联达人数范围 |
| `author_order_rate` | str | 否 | - | 达人出单率范围 |
| `is_free_shipping` | str | 否 | - | 是否包邮（"1"=是） |
| `is_new` | str | 否 | - | 是否新品 |
| `is_hot_sale` | str | 否 | - | 是否热销 |
| `is_local` | str | 否 | - | 是否本地商品 |
| `is_cross_border` | str | 否 | - | 是否跨境商品 |
| `is_sshop` | str | 否 | - | 是否全托管商品（空字符串不传递） |
| `off_shelves` | str | 否 | - | 是否已下架 |
| `commerce_type` | str | 否 | - | 电商类型筛选 |

> **注意**：`price_min` 和 `price_max` 不是直接传给上游的，后端会将它们合并为 `price_amount="min,max"` 格式传递。如果只传其中一个，缺失的部分默认为 `0`（min）或 `-1`（max）。

---

## 2. 商品筛选条件

```
GET /api/open/goods/filters
```

获取商品搜索可用的筛选条件列表，包括品类树（一级/二级/三级品类 ID 和名称）、价格区间选项等。用于构建搜索筛选 UI 或获取品类 ID。上游接口：`/api/goods/filterInfo`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `region` | str | 否 | US | 目标市场，不同市场品类树不同 |

---

## 3. 销量榜

```
GET /api/open/goods/sale-rank
```

按销量排名的商品榜单。上游接口：`/api/goods/saleRank`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 10 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `date_type` | int | 否 | - | 时间维度类型（如 1=日榜、7=周榜） |
| `date_value` | str | 否 | - | 具体时间值，与 `date_type` 配合使用 |
| `l1_cid` | str | 否 | - | 一级品类 ID |

---

## 4. 新品榜

```
GET /api/open/goods/new-product
```

新上架商品排行榜。上游接口：`/api/goods/newProduct`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 10 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `rank_type` | int | 否 | 11 | 榜单类型，固定为 11 |
| `dt` | str | 否 | - | 日期筛选 |
| `cid` | str | 否 | - | 品类 ID |
| `is_cross_border` | str | 否 | - | 是否跨境商品 |
| `is_sshop` | str | 否 | - | 是否全托管商品 |

---

## 5. 全托管商品榜

```
GET /api/open/goods/managed-rank
```

TikTok Shop 全托管（sShop）模式下的热门商品排行。上游接口：`/api/goods/sShopHotList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 10 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "8,2" | 排序规则（默认按字段8降序） |
| `date_type` | int | 否 | - | 时间维度类型 |
| `date_value` | str | 否 | - | 具体时间值 |
| `l1_cid` | str | 否 | - | 一级品类 ID |

---

## 6. 热推榜

```
GET /api/open/goods/hot-rank
```

被大量达人推广的热门商品排行。上游接口：`/api/goods/popRank`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 10 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "4,2" | 排序规则（默认按字段4降序） |
| `date_type` | int | 否 | - | 时间维度类型 |
| `date_value` | str | 否 | - | 具体时间值 |
| `l1_cid` | str | 否 | - | 一级品类 ID |

# 达人 (Influencer)

TikTok 达人数据模块，包括多维度达人搜索、各类达人榜单、以及单个达人的全部详情子接口。

---

## 搜索与榜单

### 1. 达人搜索

```
GET /api/open/influencers/search
```

多维度搜索 TikTok 达人，支持粉丝数、带货数据、互动率、联系方式等 18+ 筛选条件。上游接口：`/api/author/search`。

> **注意**：值为 `None`、空字符串或 `"-1"` 的参数不会传给上游。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "12,2" | 排序规则（12=综合排序） |
| `words` | str | 否 | - | 搜索关键词（达人昵称/简介） |
| `shop_window` | str | 否 | - | 橱窗商品数范围 |
| `follower` | str | 否 | - | 粉丝数范围，格式 `"min,max"` |
| `cid` | str | 否 | - | 带货品类 ID |
| `product` | str | 否 | - | 带货商品数范围 |
| `is_shop` | str | 否 | - | 是否拥有 TikTok Shop 店铺 |
| `verify` | str | 否 | - | 是否蓝V认证 |
| `gender` | str | 否 | - | 性别筛选 |
| `age` | str | 否 | - | 年龄段筛选 |
| `contact` | str | 否 | - | 是否公开联系方式 |
| `has_partner` | str | 否 | - | 是否签约 MCN 机构 |
| `follower_28d_count` | str | 否 | - | 近28天涨粉数范围 |
| `sale_28d_count` | str | 否 | - | 近28天带货销量范围 |
| `prod_video_28d_count` | str | 否 | - | 近28天发布带货视频数范围 |
| `prod_live_28d_count` | str | 否 | - | 近28天开播带货直播数范围 |
| `avg_28d_play_count` | str | 否 | - | 近28天场均播放量范围 |
| `avg_28d_sale_play_count` | str | 否 | - | 近28天带货视频场均播放量范围 |
| `interaction_v1_rate` | str | 否 | - | 互动率范围 |
| `like_followers_v1_rate` | str | 否 | - | 点赞粉丝比范围 |
| `first_video_time` | str | 否 | - | 首发视频时间范围 |

---

### 2. 达人榜

```
GET /api/open/influencers/rank
```

达人排行榜，支持涨粉榜、蓝V榜、热门榜三种类型。上游接口：`/api/followers/followersList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `type` | int | 否 | 1 | 榜单类型：`1`=涨粉榜、`2`=蓝V榜、`3`=热门榜 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `date_type` | int | 否 | - | 时间维度类型 |
| `date_value` | str | 否 | - | 具体时间值 |
| `cid` | str | 否 | - | 品类 ID |

---

### 3. 带货达人榜

```
GET /api/open/influencers/commerce-rank
```

按带货销售额/销量排名的达人榜单。上游接口：`/api/ecommerce/rank`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `date_type` | int | 否 | 1 | 时间维度类型 |
| `date_value` | str | 否 | - | 具体时间值 |
| `cid` | str | 否 | - | 品类 ID |

---

### 4. 黑马达人榜

```
GET /api/open/influencers/dark-horse
```

近期增长迅速的潜力达人排行（黑马榜）。上游接口：`/api/author/potential/rank`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `date_type` | int | 否 | 1 | 时间维度类型 |
| `date_value` | str | 否 | - | 具体时间值 |
| `is_ecommerce` | int | 否 | 1 | 是否仅带货达人：`1`=是 |
| `order` | str | 否 | - | 排序规则 |
| `follower` | str | 否 | - | 粉丝数范围 |
| `gender` | str | 否 | - | 性别筛选 |
| `age` | str | 否 | - | 年龄段筛选 |
| `cid` | str | 否 | - | 品类 ID |

---

## 达人详情

以下接口均需要 `uid`（达人 UID）作为必填参数。

### 5. 达人综合详情

```
GET /api/open/influencers/detail
```

获取达人的全面信息。后端内部并行请求 4 个上游接口并合并返回：
- `/api/author/v3/detail/baseInfo` — 基础资料（昵称、头像、简介、粉丝数等）
- `/api/author/v3/detail/authorIndex` — 达人指数（带货力、影响力等评分）
- `/api/author/v3/detail/getStatInfo` — 数据统计（视频数、直播数、商品数等）
- `/api/author/v3/detail/authorContact` — 联系方式（可能为空）

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `region` | str | 否 | US | 目标市场 |

**响应结构**（由后端组装）：
```json
{
  "code": 200,
  "data": {
    "base": { /* 基础资料 */ },
    "index": { /* 达人指数评分 */ },
    "stat": { /* 数据统计 */ },
    "contact": { /* 联系方式，获取失败时为空对象 */ }
  }
}
```

---

### 6. 数据趋势图

```
GET /api/open/influencers/detail/chart
```

获取达人某项数据指标在时间范围内的逐日变化趋势。上游接口：`/api/author/v3/detail/dataList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `field_type` | str | 否 | "follower" | 数据指标类型，可选：`follower`（粉丝）、`play`（播放）、`digg`（点赞）等 |
| `date_type` | int | 否 | 28 | 时间范围天数 |
| `region` | str | 否 | US | 目标市场 |

---

### 7. 粉丝画像

```
GET /api/open/influencers/detail/fans-portrait
```

获取达人粉丝的人口统计画像（性别、年龄、地域分布等）。上游接口：`/api/author/v3/detail/fansPortrait`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `date_type` | int | 否 | 28 | 时间范围天数 |
| `region` | str | 否 | US | 目标市场 |

---

### 8. 达人视频列表

```
GET /api/open/influencers/detail/videos
```

获取达人发布的视频列表，可按播放量、点赞数等排序。上游接口：`/api/author/v3/detail/videoList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 20 |
| `date_type` | int | 否 | 28 | 时间范围天数 |
| `order` | str | 否 | "play_count,2" | 排序字段。可选：`play_count`（播放量）、`digg_count`（点赞数）、`create_time`（发布时间），方向 `2`=降序 |
| `region` | str | 否 | US | 目标市场 |

---

### 9. 达人商品列表

```
GET /api/open/influencers/detail/goods
```

获取达人带货的商品列表。上游接口：`/api/author/v3/detail/goodsList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 20 |
| `date_type` | int | 否 | 28 | 时间范围天数 |
| `order` | str | 否 | "sold_count,2" | 排序字段，`sold_count`=销量降序 |
| `region` | str | 否 | US | 目标市场 |

---

### 10. 达人直播列表

```
GET /api/open/influencers/detail/live
```

获取达人的直播记录列表。上游接口：`/api/author/v3/detail/liveList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 20 |
| `date_type` | int | 否 | 28 | 时间范围天数 |
| `order` | str | 否 | "create_time,2" | 排序字段，`create_time`=最新优先 |
| `region` | str | 否 | US | 目标市场 |

---

### 11. 带货品类分布

```
GET /api/open/influencers/detail/category-list
```

获取达人带货商品的品类分布（各品类占比）。上游接口：`/api/author/v3/detail/categoryList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `region` | str | 否 | US | 目标市场 |

---

### 12. 活跃时段分析

```
GET /api/open/influencers/detail/active-range
```

获取达人的发布/活跃时段分布（一周内按小时统计）。上游接口：`/api/author/v3/detail/authorActiveRange`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `date_type` | int | 否 | 28 | 时间范围天数 |
| `region` | str | 否 | US | 目标市场 |

---

### 13. 相似达人

```
GET /api/open/influencers/detail/similarity
```

获取与指定达人风格/品类相似的其他达人列表。上游接口：`/api/author/v3/detail/similarityList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 20 |
| `region` | str | 否 | US | 目标市场 |

---

### 14. 粉丝活跃分析

```
GET /api/open/influencers/detail/fans-analysis
```

获取达人粉丝的活跃度分析数据。上游接口：`/api/author/v3/detail/authorFansAnalysis`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `region` | str | 否 | US | 目标市场 |

---

### 15. 带货总览

```
GET /api/open/influencers/detail/cargo-summary
```

获取达人的带货业绩总览（总销量、总销售额、平均客单价等汇总数据）。上游接口：`/api/author/v3/detail/cargoSummary`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `region` | str | 否 | US | 目标市场 |

---

### 16. 常用标签

```
GET /api/open/influencers/detail/labels
```

获取达人视频中常用的话题标签列表。上游接口：`/api/author/v3/detail/labelList`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `uid` | str | ✅ | - | 达人 UID |
| `region` | str | 否 | US | 目标市场 |

# 商品详情 (Product Detail)

根据商品 ID 获取单个商品的各维度详细数据，包括基础信息、销售趋势、带货视频/达人、评价、直播等。

---

## 1. 商品基础信息

```
GET /api/open/goods/detail
```

获取单个商品的基础信息，包括标题、价格、图片、品类、店铺等。上游接口：`/api/goods/v3/base`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `product_id` | str | ✅ | - | 商品 ID |
| `region` | str | 否 | US | 目标市场 |

---

## 2. 销售趋势概览

```
GET /api/open/product/overview
```

获取商品在指定时间范围内的销售趋势数据（销量、销售额、关联达人数等）。上游接口：`/api/goods/v3/overview`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `product_id` | str | ✅ | - | 商品 ID |
| `d_type` | int | 否 | 28 | 时间范围天数，可选 7、28、90 |
| `region` | str | 否 | US | 目标市场 |

---

## 3. 带货视频列表

```
GET /api/open/product/videos
```

获取推广该商品的视频列表。上游接口：`/api/goods/v3/video`。

> **内部固定参数**：`d_type=0`、`is_promoted=-1`（表示不限推广类型），调用方无需传递。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `product_id` | str | ✅ | - | 商品 ID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 5 | 每页条数，最大 10 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `date_type` | int | 否 | 28 | 时间范围（7/28/90天） |
| `region` | str | 否 | US | 目标市场 |

---

## 4. 带货达人列表

```
GET /api/open/product/authors
```

获取推广该商品的达人列表。上游接口：`/api/goods/v3/author`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `product_id` | str | ✅ | - | 商品 ID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 5 | 每页条数，最大 10 |
| `order` | str | 否 | "2,2" | 排序规则 |
| `ecommerce_type` | str | 否 | "all" | 电商类型筛选，`all` 表示全部 |
| `region` | str | 否 | US | 目标市场 |

---

## 5. 商品评价

```
GET /api/open/product/reviews
```

获取商品的用户评价列表。上游接口：`/api/goods/reviewList`。

> **内部固定参数**：`near_day=0`（不限时间）、`is_like=0`（不筛选好评）。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `product_id` | str | ✅ | - | 商品 ID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 5 | 每页条数，最大 10 |
| `region` | str | 否 | US | 目标市场 |

---

## 6. 直播带货列表

```
GET /api/open/product/live
```

获取通过直播带货推广该商品的直播间列表。上游接口：`/api/goods/v3/live`。

> **内部固定参数**：`live_type="all"`（不筛选直播类型）。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `product_id` | str | ✅ | - | 商品 ID |
| `page` | int | 否 | 1 | 页码 |
| `pagesize` | int | 否 | 5 | 每页条数，最大 10 |
| `d_type` | int | 否 | 28 | 时间范围天数 |
| `order` | str | 否 | "2,2" | 排序规则 |
| `region` | str | 否 | US | 目标市场 |

# 店铺 (Shop)

TikTok Shop 店铺数据模块，提供店铺搜索、详情、商品列表、关联达人等。

---

## 1. 店铺筛选条件

```
GET /api/open/shops/filter-info
```

获取店铺搜索可用的筛选条件（品类、店铺类型等选项列表）。上游接口：`/api/shop/filterInfo`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `region` | str | 否 | US | 目标市场 |

---

## 2. 店铺搜索

```
GET /api/open/shops/search
```

多条件搜索 TikTok Shop 店铺。上游接口：`/api/shop/V3/search`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 20 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `words` | str | 否 | - | 搜索关键词（店铺名称） |
| `cid` | str | 否 | - | 品类 ID |
| `is_sshop` | str | 否 | - | 是否全托管店铺（空字符串不传递） |
| `shop_type` | str | 否 | - | 店铺类型 |
| `shop_position` | str | 否 | - | 店铺所在地 |
| `date_type` | int | 否 | - | 时间维度类型 |
| `date_value` | str | 否 | - | 具体时间值 |
| `sold_count` | str | 否 | - | 销量范围 |
| `sale_amount` | str | 否 | - | 销售额范围 |
| `author_count` | str | 否 | - | 关联达人数范围 |
| `rating` | str | 否 | - | 店铺评分范围 |

---

## 3. 店铺详情

```
GET /api/open/shops/detail
```

获取单个店铺的基础详情信息。上游接口：`/api/shop/V3/base`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 店铺 ID |
| `region` | str | 否 | US | 目标市场 |

---

## 4. 店铺商品列表

```
GET /api/open/shops/products
```

获取指定店铺内的商品列表。上游接口：`/api/shop/V3/goods`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 店铺 ID |
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 20 | 每页条数，最大 50 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `region` | str | 否 | US | 目标市场 |

---

## 5. 店铺关联达人

```
GET /api/open/shops/authors
```

获取与指定店铺有合作关系的达人列表。上游接口：`/api/shop/V3/author`。

> **注意**：此接口使用 `seller_id` 参数（非 `id`），与其他店铺接口不同。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `seller_id` | str | ✅ | - | 卖家 ID（注意：不是店铺 ID `id`） |
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 20 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |

# 视频 (Video)

TikTok 视频数据模块，提供热门视频搜索、视频商品榜、以及单个视频的详情/趋势/带货商品/相似视频等。

---

## 1. 热门视频搜索

```
GET /api/open/videos/hot
```

搜索 TikTok 上的热门带货视频，支持按关键词、品类、播放量、互动率等筛选。上游接口：`/api/video/search`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "2,2" | 排序规则 |
| `d_type` | int | 否 | 7 | 时间范围天数（如 1/3/7/28） |
| `words` | str | 否 | - | 搜索关键词 |
| `cid` | str | 否 | - | 品类 ID |
| `follower` | str | 否 | - | 作者粉丝数范围，格式 `"min,max"` |
| `play` | str | 否 | - | 播放量范围 |
| `digg` | str | 否 | - | 点赞数范围 |
| `interact_rate` | str | 否 | - | 互动率范围 |
| `bind_product` | str | 否 | - | 是否关联商品（空字符串不传递） |

---

## 2. 视频商品榜

```
GET /api/open/videos/rank
```

按视频维度聚合的商品排行榜，展示哪些商品通过视频获得最多曝光。上游接口：`/api/video/hotGoodsVideoGroupByProduct`。

> **注意**：上游返回 base64 编码的 JSON，后端自动解码后返回标准 JSON。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |
| `order` | str | 否 | "1,2" | 排序规则 |
| `rank_type` | int | 否 | 7 | 时间维度（7=近7天） |

---

## 3. 视频详情

```
GET /api/open/videos/detail
```

获取单个视频的详细信息，包括基础概览和数据统计。后端内部并行请求两个上游接口（`/api/video/overview` 和 `/api/video/overviewData`），合并后返回。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 视频 ID |
| `region` | str | 否 | US | 目标市场 |

**响应结构**（非标准上游格式，由后端组装）：
```json
{
  "code": 200,
  "data": {
    "overview": { /* 视频基础信息：标题、作者、发布时间、关联商品等 */ },
    "stats": { /* 数据统计：播放量、点赞、评论、分享等 */ }
  }
}
```

---

## 4. 视频数据趋势

```
GET /api/open/videos/detail/trend
```

获取视频在指定时间范围内的数据变化趋势（播放量、点赞数等按日变化）。上游接口：`/api/video/V2/base`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 视频 ID |
| `d_type` | int | 否 | 7 | 时间范围天数 |
| `region` | str | 否 | US | 目标市场 |

---

## 5. 视频带货商品

```
GET /api/open/videos/detail/goods
```

获取某个视频关联推广的商品列表。上游接口：`/api/video/v2/goods`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 视频 ID |
| `page` | int | 否 | 1 | 页码，≥1 |
| `pagesize` | int | 否 | 10 | 每页条数，最大 50 |
| `region` | str | 否 | US | 目标市场 |

---

## 6. 相似视频

```
GET /api/open/videos/detail/similar
```

获取与指定视频内容相似的视频列表。上游接口：`/api/video/similar`。

**参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `id` | str | ✅ | - | 视频 ID |
| `region` | str | 否 | US | 目标市场 |