# 抖音数据 API | Douyin comments profile video search (`socialdatax/socialdatax-douyin-data-api`) Actor

社媒数据助手 SocialDataX 提供只读抖音 / Douyin data API，重点支持 Douyin comments / 抖音评论数据、Douyin profile / 抖音博主信息、Douyin video search / 抖音作品搜索、video details、creator videos、creator series 和 Douyin hot search / 热榜。

- **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:** 25 total users, 10 monthly users, 94.6% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## 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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 抖音数据 API | Douyin comments profile video search

这是社媒数据助手 SocialDataX 的 Apify Actor 适配层，提供只读抖音 / Douyin data API，面向 Douyin comments / 抖音评论数据、Douyin profile / 抖音博主信息、Douyin video search / 抖音作品搜索、creator videos、Douyin hot search / 热榜和批量 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 is designed for Douyin comments export, Douyin profile data, video search, video details, comment replies, creator videos, creator series, hot-list data, and CSV / Excel / JSON exports.

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

### Features / 支持能力

- 作品搜索 / video 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/>

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

- Website: <https://socialdatax.com/>

### 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_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_detail` 和 `get_video_comments`。`get_video_sub_comments` 不使用 `url`，请先跑 `get_video_comments` 再复制 Dataset 行里的真实 `aweme_id + comment_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`。
- `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 / 输入示例

作品搜索：

```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_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，避免丢失 `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 时必填；其它 operation 可留空。

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

仅 operation=search\_videos 时使用。general=综合，time\_descending=最新发布优先，like\_count\_descending=最多点赞优先。

## `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=图文。

## `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\_video\_detail、get\_video\_comments 时至少提供 url 或 aweme\_id 之一；同时提供时优先使用 url。推荐直接粘贴抖音作品链接、短链接或分享文案。评论回复 get\_video\_sub\_comments 不使用 url；请先运行 get\_video\_comments，再复制 Dataset 行里的真实 aweme\_id + comment\_id。

## `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`):

搜索、评论、评论回复、博主作品列表、博主合集列表继续翻页时传入上一页返回的完整 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",
  "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("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=socialdatax/socialdatax-douyin-data-api",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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