# 抖音数据 API：商品、用户、视频与评论 | Douyin API (`socialdatax/socialdatax-douyin-data-api`) Actor

社媒数据助手 SocialDataX 提供只读抖音 / Douyin data API，支持商品搜索、用户搜索、作品搜索、评论与回复、作品详情、博主信息、博主作品、合集/短剧列表和热榜，并可导出 Apify Dataset、CSV、Excel。

- **URL**: https://apify.com/socialdatax/socialdatax-douyin-data-api.md
- **Developed by:** [SocialDataX](https://apify.com/socialdatax) (community)
- **Categories:** Developer tools, Videos, Social media
- **Stats:** 1,316 total users, 399 monthly users, 99.1% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $4.99 / 1,000 dataset items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 抖音数据 API：商品、用户、视频与评论 | Douyin API

这是社媒数据助手 SocialDataX 的 Apify Actor 适配层，提供只读抖音 / Douyin data API，面向商品搜索与详情、用户搜索、作品搜索、评论数据、博主信息、热榜和批量 Dataset export 场景。

Apify 用户无需配置 SocialDataX API Key；直接通过 Apify Console、Apify API、Dataset export 或自动化工作流运行即可。

### Overview / 概览

This Actor turns SocialDataX's read-only Douyin data API into an Apify Dataset workflow. It supports product search and details, user search, comments export, creator data, video search and details, creator series, hot-list data, and CSV / Excel / JSON exports.

这个 Actor 适合把抖音商品搜索与详情、用户搜索、评论数据、博主信息、视频搜索、博主作品列表、合集/短剧列表和热榜数据导出到 Apify Dataset，再通过 CSV、Excel、JSON、JSONL 或 Apify API 使用。

### Features / 支持能力

- 作品搜索 / video search / 抖音视频数据
- 商品搜索 / product search
- 商品详情 / product details
- 用户搜索 / user search
- 作品详情 / video details / 单条视频数据
- 评论列表 / comments / 抖音评论数据
- 评论回复 / comment replies
- 博主信息 / creator profiles / profile data
- 博主作品列表 / creator videos
- 博主合集/短剧列表 / creator series
- 热榜 / hot list

This Actor is a read-only, unofficial data API integration. It is not affiliated with Douyin or ByteDance.

### Support / 联系我们

如果 run 失败、需要更高用量，或想接入批量数据工作流，请通过 SocialDataX support 联系我们：

- Website: <https://socialdatax.com/ai?from=apify>

If a run fails, you need higher limits, or you want to discuss a bulk data workflow, contact SocialDataX support:

- Website: <https://socialdatax.com/ai?from=apify>

### Input / 输入字段

先选择 `operation`，再填写该 operation 需要的字段。Apify 表单里其它字段可以留空；不要用无关字段替代当前 operation 的必填字段，否则 Actor 会返回错误或修正提示，避免跑错查询。

| Operation | 必填字段 | 可选字段 | 说明 |
| --- | --- | --- | --- |
| `search_videos` | `keyword` | `sort_type`, `publish_time_range`, `duration_range`, `content_type`, `page_token`, `max_items`, `auto_paginate` | 按关键词搜索抖音作品，支持排序和筛选，默认会自动翻页直到达到 `max_items`。 |
| `search_products` | `keyword` | `sort_type`, `min_price`, `max_price`, `only_live`, `dispatch_within_24h`, `shipping_insurance`, `seven_day_return`, `selling_point`, `official_store`, `page_token`, `max_items`, `auto_paginate` | 按关键词搜索商品，支持销量/价格排序和服务条件筛选。 |
| `get_product_detail` | `product_id` 或 `url` 至少填一个 | 无 | 获取单个抖音商品详情；两者都填时优先使用 `url`。 |
| `search_users` | `keyword` | `follower_count_range`, `user_type`, `page_token`, `max_items`, `auto_paginate` | 按昵称、抖音号、账号名或达人名称搜索用户，并按粉丝数和认证类型筛选。 |
| `search_hot_list` | 无 | `max_items` | 抖音热榜，请求一次并按 `max_items` 限制写入 Dataset。 |
| `get_video_detail` | `aweme_id` 或 `url` 至少填一个 | 无 | 获取单个抖音作品详情；两者都填时优先使用 `url`。 |
| `get_video_comments` | `aweme_id` 或 `url` 至少填一个 | `page_token`, `max_items`, `auto_paginate` | 获取一级评论列表；两者都填时优先使用 `url`。 |
| `get_video_sub_comments` | `aweme_id`, `comment_id` | `page_token`, `max_items`, `auto_paginate` | 获取某条一级评论下的回复。先运行 `get_video_comments`，从 Dataset 复制 `reply_count > 0` 行里的 `aweme_id + comment_id`。 |
| `get_user_info` | `sec_user_id` 或 `profile_url` 至少填一个 | 无 | 获取博主信息；两者都填时优先使用 `profile_url`。 |
| `list_user_videos` | `sec_user_id` 或 `profile_url` 至少填一个 | `page_token`, `max_items`, `auto_paginate` | 获取博主作品列表；两者都填时优先使用 `profile_url`。 |
| `list_user_series` | `sec_user_id` 或 `profile_url` 至少填一个 | `page_token`, `max_items`, `auto_paginate` | 获取博主合集/短剧列表；两者都填时优先使用 `profile_url`。 |

### Input tips / 字段填写建议

- `url`: 商品详情可粘贴抖音商品短链接、商品页面链接或分享文案；作品详情和评论可粘贴作品链接、短链接或分享文案。`get_video_sub_comments` 不使用 `url`。
- `product_id`: 只用于 `get_product_detail`；用户已提供完整 ID 时直接使用，无需先搜索，否则可从 `search_products` Dataset 行原样复制；不要填 `sku_id` 或搜索词。
- `profile_url`: 推荐直接粘贴抖音主页链接、短链接或分享文案，适用于 `get_user_info`、`list_user_videos` 和 `list_user_series`。
- `aweme_id`: 只填真实作品 ID；如果把作品链接或分享文案误填到 `aweme_id`，Actor 会尽量自动按 `url` 处理。`get_video_sub_comments` 例外，它必须使用 `get_video_comments` Dataset 行里的真实 `aweme_id`。
- `sec_user_id`: 只填真实 `sec_user_id` / `author_sec_user_id`。不要填昵称、主页名称或抖音号；如果只有主页链接或分享文案，请填 `profile_url`。
- `keyword`: 根据 operation 搜索作品、商品或用户；商品价格、服务条件和排序请填写对应筛选字段，不要拼进关键词。
- `page_token`: 搜索和列表接口续页时原样使用上一页 Dataset 行的完整 `page_next_page_token`（对应 API 返回的 `next_page_token`）；修改关键词或筛选条件后请清空令牌重新搜索。
- `comment_id`: 只填 `get_video_comments` Dataset row 里的 `comment_id`。请选择 `reply_count > 0` 的一级评论行，不要填评论内容、昵称或其它文本。

如果用户把作品链接填到博主类 operation、把主页链接填到作品类 operation，或在 `get_video_sub_comments` 的 `aweme_id` 里粘贴作品链接/分享文案，Actor 会跳过 SocialDataX API 请求并在 `OUTPUT` 写入中英文 warning 和支持链接，避免因为明显可修正的输入问题直接失败。

### Examples / 输入示例

商品详情输出使用 `variant_groups` 表示 `name/options` 可选规格组，`shipping.text` 表示发货说明，`shipping.fee` 表示运费展示文本；不再返回旧字段 `specifications`、`shipping_text`、`shipping_fee_text`。`price` / `discount_price` 是起售价 / 优惠后起售价，不是指定 SKU 的最终实付价；`sales_text` 保留销量原文，带 `+` 的数量不是精确销量。`sold_count` 提供可解析的已售数量（如 `已售 178` 返回 `178`）；不带 `+` 的万级展示数量换算为整数（如 `已售 1.5万` 返回 `15000`），不代表精确销量，须结合原文解读。带 `+`、缺失或无法解析时返回 `null`，明确的 `已售 0` 返回 `0`。`on_sale` 不等同于指定 SKU 有库存或当前用户可购买。历史 Dataset 行不会自动改写。

作品搜索：

```json
{
  "operation": "search_videos",
  "keyword": "露营",
  "sort_type": "general",
  "publish_time_range": "all",
  "duration_range": "all",
  "content_type": "all",
  "max_items": 20,
  "auto_paginate": true
}
```

商品搜索：

```json
{
  "operation": "search_products",
  "keyword": "露营桌",
  "sort_type": "sales_descending",
  "min_price": 100,
  "max_price": 500,
  "shipping_insurance": true,
  "max_items": 50,
  "auto_paginate": true
}
```

商品详情：

```json
{
  "operation": "get_product_detail",
  "url": "https://v.douyin.com/VnF1KS4vmmQ/"
}
```

用户搜索：

```json
{
  "operation": "search_users",
  "keyword": "露营",
  "follower_count_range": "10k_to_100k",
  "user_type": "all",
  "max_items": 50,
  "auto_paginate": true
}
```

热榜：

```json
{
  "operation": "search_hot_list",
  "max_items": 20
}
```

作品详情：

```json
{
  "operation": "get_video_detail",
  "url": "https://www.douyin.com/video/7648208200076573925"
}
```

评论列表：

```json
{
  "operation": "get_video_comments",
  "url": "https://www.douyin.com/video/7648208200076573925",
  "page_token": "",
  "max_items": 20,
  "auto_paginate": true
}
```

评论回复：

```json
{
  "operation": "get_video_sub_comments",
  "aweme_id": "7648208200076573925",
  "comment_id": "7648330123242324788",
  "page_token": "",
  "max_items": 20,
  "auto_paginate": true
}
```

`comment_id` 来自 `get_video_comments` 的 Dataset 结果。选择 `reply_count > 0` 的一级评论行，复制该行的 `aweme_id` 和 `comment_id`。

博主信息：

```json
{
  "operation": "get_user_info",
  "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAVbcQXT1UykaJ9ceFzkeTICuowUGwD57JWzQTd5UjN2A"
}
```

博主作品列表：

```json
{
  "operation": "list_user_videos",
  "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAVbcQXT1UykaJ9ceFzkeTICuowUGwD57JWzQTd5UjN2A",
  "page_token": "",
  "max_items": 20,
  "auto_paginate": true
}
```

博主合集/短剧列表：

```json
{
  "operation": "list_user_series",
  "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAeTw694TE8HsvvitqbV3ot9pqHh6n6MThBKz2pECOOn4",
  "page_token": "",
  "max_items": 20,
  "auto_paginate": true
}
```

`max_items` 默认 `50`，最大 `1000`。`auto_paginate=false` 时只请求当前 `page_token`。热榜不需要分页参数，Actor 会请求一次，并按 `max_items` 限制写入 Dataset 的热榜条目数。

如果用户在 Apify run options 里设置了更低的 paid Dataset item 上限，Actor 会把列表类 `max_items` 自动裁剪到该上限，避免超预算请求过多页面。
如果该上限为 `0`，Actor 会直接结束并在 `OUTPUT` 写入 warning，不会请求 SocialDataX API。

### Apify plan requirements / Apify 计划要求

持续使用需要 Apify paid plan。Apify free plan 用户有 5 次 SocialDataX API request 试用额度；每次请求一个接口页面计 1 次，`auto_paginate=true` 时每翻一页都会计入一次。试用额度用完后，请升级 Apify 计划继续使用。

Ongoing use requires an Apify paid plan. Free-plan users get a 5-request SocialDataX API trial. Each requested page counts as one request, so `auto_paginate=true` can consume multiple requests in one run.

### Output / 输出

Actor 会把结果写入 Apify Dataset，适合 JSON、CSV、Excel / XLSX、JSONL 等格式导出。

列表类接口会为 `items[]` 或 `hot_items[]` 中的每个元素写入一条扁平 dataset row：

```json
{
  "operation": "get_video_comments",
  "item_index": 1,
  "query_aweme_id": "7648208200076573925",
  "query_page_token": "",
  "query_max_items": 20,
  "query_auto_paginate": true,
  "aweme_id": "7648208200076573925",
  "comment_id": "7648330123242324788",
  "content": "这套露营装备清单很实用。",
  "reply_count": 8,
  "author_sec_user_id": "MS4wLjABAAAALynj49NNn56hWtVWVcPsfDfNnpMSC-LwECb-ChhQd4lRlQwduE3zeDvy4aj3YTyF",
  "author_name": "露营爱好者",
  "page_request_index": 1,
  "page_item_count": 20,
  "page_next_page_token": "next-token",
  "page_has_more": true
}
```

详情类接口会写入一条 dataset row。`author`、`video`、`music` 等常见对象会展开为 `author_*`、`video_*`、`music_*` 字段；`live_info` 保留为直播摘要对象，未直播时为 `null`。图片和数组字段保留 JSON 值。

如果某一页 `items` 为空但仍有分页信息，且本次 run 没有继续拿到后续实际 item，Actor 会写入一条 `empty_page=true` 的 summary row，避免丢失 `page_next_page_token`。如果自动翻页后拿到了后续实际 item，中间空页不会写入 Dataset row，也不会占用 `max_items`。如果空页已经没有下一页，则不会写入 Dataset row。

如果 run 失败，`OUTPUT` 会保留一条轻量失败摘要，方便在 Apify 控制台里直接看到请求次数、状态码和简要错误信息。

### Apify API usage / Apify API 调用

同步运行并直接获取 Dataset items：

```bash
curl -X POST "https://api.apify.com/v2/acts/socialdatax~socialdatax-douyin-data-api/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "search_videos",
    "keyword": "露营",
    "max_items": 20,
    "auto_paginate": true
  }'
```

Python client 示例：

```python
from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("socialdatax/socialdatax-douyin-data-api").call(run_input={
    "operation": "search_videos",
    "keyword": "露营",
    "max_items": 20,
    "auto_paginate": True,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

### Pricing / 费用

Apify 用户按 Actor 页面展示的 Apify 价格和用量计费，不需要购买或配置 SocialDataX API Key。

# Actor input Schema

## `operation` (type: `string`):

先选择要调用的抖音数据 API / Douyin data API 能力，然后只填写该 operation 需要的字段；不要用无关字段替代必填字段，否则 Actor 会返回错误或修正提示，避免跑错查询。持续使用需要 Apify paid plan；free plan 用户有 5 次 SocialDataX API request 试用额度。Choose the operation first, then fill only the fields used by that operation.

## `keyword` (type: `string`):

operation=search_videos、search_products 或 search_users 时必填；分别用于作品、商品或用户搜索。其它 operation 可留空。

## `sort_type` (type: `string`):

operation=search_videos 时支持 general、time_descending、like_count_descending；operation=search_products 时支持 general、sales_descending、price_ascending、price_descending。search_users 仅兼容共享表单默认值 general，填写其它排序值会返回提示；非搜索 operation 会忽略该字段。

## `publish_time_range` (type: `string`):

仅 operation=search_videos 时使用。all=不限，day=一天内，week=一周内，half_year=半年内。

## `duration_range` (type: `string`):

仅 operation=search_videos 时使用。all=不限，under_1_minute=1 分钟以下，one_to_five_minutes=1-5 分钟，over_5_minutes=5 分钟以上。

## `content_type` (type: `string`):

仅 operation=search_videos 时使用。all=不限，video=视频，image=图文。

## `follower_count_range` (type: `string`):

仅 operation=search_users 时使用，用于按公开粉丝数量范围筛选用户。

## `user_type` (type: `string`):

仅 operation=search_users 时使用，用于筛选普通用户、企业认证或个人认证用户。

## `min_price` (type: `integer`):

仅 operation=search_products 时使用，单位为元；必须为正整数。留空表示不限。

## `max_price` (type: `integer`):

仅 operation=search_products 时使用，单位为元；必须为正整数且不小于最低价格。留空表示不限。

## `only_live` (type: `boolean`):

仅 operation=search_products 时使用。开启后只返回当前正在直播的商品。

## `dispatch_within_24h` (type: `boolean`):

仅 operation=search_products 时使用。开启后只返回支持 24 小时内发货的商品。

## `shipping_insurance` (type: `boolean`):

仅 operation=search_products 时使用。开启后只返回支持运费险的商品。

## `seven_day_return` (type: `boolean`):

仅 operation=search_products 时使用。开启后只返回支持 7 天无理由退货的商品。

## `selling_point` (type: `string`):

仅 operation=search_products 时使用。all=不限，high_sales=月销过万，high_rating=好评多。

## `official_store` (type: `boolean`):

仅 operation=search_products 时使用。开启后只返回带抖音旗舰标识的商品。

## `product_id` (type: `string`):

operation=get_product_detail 时至少提供 product_id 或 url 之一；同时提供时优先使用 url。product_id 可从 search_products Dataset 行原样复制，不要填写 sku_id 或搜索词。

## `aweme_id` (type: `string`):

operation=get_video_detail、get_video_comments、get_video_sub_comments 时使用；如果只有作品链接、短链接或分享文案，请直接填 url。详情和评论列表至少提供 aweme_id 或 url 之一，同时提供时优先使用 url。评论回复必须使用 get_video_comments Dataset 行里的真实 aweme_id + comment_id，不支持链接或分享文案。

## `url` (type: `string`):

operation=get_product_detail 时可填写抖音商品短链接、商品页面链接或分享文案；operation=get_video_detail、get_video_comments 时可填写作品链接、短链接或分享文案。对应 ID 与 url 同时提供时优先使用 url。评论回复 get_video_sub_comments 不使用 url。

## `sec_user_id` (type: `string`):

operation=get_user_info、list_user_videos、list_user_series 时至少提供 sec_user_id 或 profile_url 之一；同时提供时优先使用 profile_url。只填真实 sec_user_id，不要填昵称、主页名称或抖音号；如果只有主页链接、短链接或分享文案，请直接填 profile_url。

## `profile_url` (type: `string`):

operation=get_user_info、list_user_videos、list_user_series 时至少提供 profile_url 或 sec_user_id 之一；同时提供时优先使用 profile_url。强烈推荐直接粘贴抖音主页链接、短链接或分享文案。

## `comment_id` (type: `string`):

仅 operation=get_video_sub_comments 时必填。先运行 get_video_comments，在 Dataset 里找到 reply_count > 0 的一级评论行，复制该行的 comment_id；不要填评论内容、昵称或其它文本。

## `page_token` (type: `string`):

作品搜索、商品搜索、用户搜索、评论、评论回复、博主作品列表、博主合集列表继续翻页时，原样传入上一页 Dataset 行的 page_next_page_token（对应 API 返回的 next_page_token）；第一页留空。auto_paginate=true 时通常不用手动填写。

## `max_items` (type: `integer`):

最多写入多少条 Dataset item。对搜索、评论、评论回复、博主作品列表、博主合集列表用于限制自动翻页结果；对热榜用于限制本次导出的热榜条目数。较大的值可能触发多次 SocialDataX API request。

## `auto_paginate` (type: `boolean`):

开启后 Actor 会按 next_page_token 继续请求，直到达到 max_items 或没有下一页。关闭时只请求当前 page_token。每翻一页计 1 次 SocialDataX API request。When enabled, each page request counts as one SocialDataX API request.

## Actor input object example

```json
{
  "operation": "search_videos",
  "keyword": "露营",
  "sort_type": "general",
  "publish_time_range": "all",
  "duration_range": "all",
  "content_type": "all",
  "follower_count_range": "all",
  "user_type": "all",
  "only_live": false,
  "dispatch_within_24h": false,
  "shipping_insurance": false,
  "seven_day_return": false,
  "selling_point": "all",
  "official_store": false,
  "max_items": 50,
  "auto_paginate": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

Open flat result rows written to the default Apify Dataset. Export as JSON, CSV, Excel / XLSX, or JSONL.

## `keyValueStore` (type: `string`):

Open the default key-value store. The OUTPUT record contains operation, item count, request count, page-level response summaries, non-fatal warnings, and lightweight failure details when a run fails.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("socialdatax/socialdatax-douyin-data-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("socialdatax/socialdatax-douyin-data-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call socialdatax/socialdatax-douyin-data-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,socialdatax/socialdatax-douyin-data-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/c1oPt25gVpqXdpW3K/builds/VJFq0Jle2YLLKABNN/openapi.json