# Douyin Transcripts Scraper (`khadinakbar/douyin-transcripts-scraper`) Actor

Extract public Douyin speech transcripts from URLs, share links or IDs. Get original text, timed cues, optional translation and SRT/VTT/TXT/JSON exports. Use for content analysis; discovery needs a Douyin search tool. $0.019/audio minute; translation adds $0.009/minute, plus platform usage.

- **URL**: https://apify.com/khadinakbar/douyin-transcripts-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Social media, Videos, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $19.00 / 1,000 delivered transcript minutes

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

## Douyin Transcripts Scraper — Subtitles & Translation

Extract spoken content from public Douyin (抖音) videos into original text, timestamped cues and subtitle files. Supply video URLs, mobile share links, share text or numeric video IDs. Use it for China-market content research, subtitle editing, multilingual review and AI analysis of videos you are authorized to process.

**Private candidate. End-to-end source and translated delivery has been observed. Broader release acceptance, comparative accuracy and target pricing remain under validation. This Actor is not ready for Store publication.**

### What you receive

One dataset row per delivered video transcript, with full JSON and TXT exports. SRT and WebVTT exports are enabled by default with no separate export event. Optional translation retains original speech and adds translated text and aligned subtitle files.

| Field | Meaning |
|---|---|
| `transcript`, `segments` | Original spoken text and cues with start/end seconds |
| `translatedTranscript`, `translatedSegments` | Optional translation with the same cue boundaries |
| `transcriptSource`, `timestampSource` | Native captions or speech recognition; model timings are estimates |
| `transcriptComplete`, `translationStatus` | Explicit completeness and translation outcome |
| `jsonUrl`, `txtUrl`, `srtUrl`, `vttUrl` | Full transcript and subtitle export links |
| `words` | Optional speech-model word timings; native captions have cue timing only |
| `awemeId`, `videoUrl`, `scrapedAt` | Identity, canonical source URL and UTC collection time |
| Caption, engagement, creator details | Available public context, separate from spoken words |

For public metadata without speech, pair this Actor with [Douyin Video Scraper](https://apify.com/khadinakbar/douyin-video-scraper). For audience discussion, pair this Actor with [Douyin Comments Scraper](https://apify.com/khadinakbar/douyin-comments-scraper). Use this Actor when you already have public video links and need spoken text. Do not use this Actor for keyword discovery or creator-profile collection.

### How to get Douyin transcripts

Add public video links, choose original speech or a translation, set duration and event budgets, then run. Read both the dataset and `RUN_SUMMARY`; use each row's export links for full files.

```json
{
  "videoUrls": ["https://www.douyin.com/video/7534679152504376595"],
  "maxVideos": 10,
  "targetLanguage": "original",
  "exportSubtitles": true,
  "maxTotalMinutes": 30,
  "maxChargeUsd": 5
}
```

Desktop `/video/` links, `iesdouyin.com/share/video/` links, `v.douyin.com` links, feed links with `modal_id`, pasted share text and bare numeric IDs are accepted. Up to 100 inputs are accepted; `maxVideos` defaults to 10. Canonical duplicates are removed before delivery and billing.

### Input options

| Option | Default | Scope |
|---|---|---|
| `transcriptMode` | `auto` | Native captions then speech; `speech` regenerates audio text; `captions` uses existing tracks only |
| `targetLanguage` | `original` | Original speech or one of 51 configured translation targets |
| `includeWordTimestamps` | `false` | Word timing on the speech-recognition route |
| `exportSubtitles` | `true` | SRT and WebVTT exports; TXT/JSON always retained |
| `responseFormat` | `detailed` | `concise` gives 1500-character and ten-cue previews with full export links |
| `maxVideos` | `10` | 1–100 videos per batch |
| `maxDurationMinutes` | `10` | Universal 1–30 minute limit per video |
| `maxTotalMinutes` | `30` | 1–300 rounded audio minutes per run |
| `maxChargeUsd` | `5` | Transcript and translation event budget; startup additional; platform usage paid by the creator |
| `maxRunSeconds` | `900` | 60–3600 second execution deadline |

The Actor never presents post captions, hashtags, music titles or reusable music tracks as spoken transcripts. Unknown counts remain null. The lightweight public page can omit comments, shares, saves, music and follower counts; metadataUnavailableFields identifies those gaps and metadataSourceUrl records the page used.

### Translation and subtitle workflow

```json
{
  "videoUrls": ["7534679152504376595"],
  "targetLanguage": "en",
  "transcriptMode": "speech",
  "includeWordTimestamps": true,
  "exportSubtitles": true
}
```

The form offers 51 translation targets, including English, Arabic, Spanish, Hindi, Japanese and Korean. These are implemented settings, not individually verified language-quality claims. Original speech is always retained. Translation must preserve every cue index. Incomplete output is rejected; failed translation preserves the source transcript, reports partial delivery and incurs no translation event.

A researcher reviewing Mandarin product demonstrations can collect source speech, add English captions for colleagues and keep both languages together. An editor can import SRT or VTT into a compatible editing tool and check timings against the video. This workflow does not verify claims made by the speaker.

### Output example

This shortened example illustrates the contract; it is not a cloud-run sample. Full rows include metadata and export links.

```json
{
  "awemeId": "7534679152504376595",
  "videoUrl": "https://www.douyin.com/video/7534679152504376595",
  "durationSeconds": 67.756,
  "status": "success",
  "transcript": "你好，欢迎观看。",
  "segments": [{"start": 0, "end": 2.5, "text": "你好，欢迎观看。"}],
  "transcriptSource": "speech-recognition",
  "timestampSource": "model-estimated",
  "transcriptComplete": true,
  "targetLanguage": "en",
  "translatedTranscript": "Hello, welcome.",
  "translatedSegments": [{"start": 0, "end": 2.5, "text": "Hello, welcome."}],
  "translationStatus": "complete",
  "billedMinutes": 2,
  "responseTruncated": false
}
```

### Pricing and cost controls

Private candidate pricing is **Pay per event with creator-funded platform usage**, with equal features and event rates on every plan. Check the live [Pricing tab](https://apify.com/khadinakbar/douyin-transcripts-scraper/pricing) after private setup and before running.

| Event | Proposed price |
|---|---:|
| Actor start | $0.00005 per allocated GB, minimum one event |
| Delivered source transcript | $0.019 per started audio minute |
| Successful optional translation | Additional $0.009 per started audio minute |

Exports have no separate event charge. A 67.756-second video rounds to two minutes: $0.038 for source text, or $0.056 with translation. At default 1 GB memory, startup adds $0.00005. Platform usage is paid by the creator; verify the effective Pricing tab before running. The $5 per 1,000 short-video target is not an active launch price. A batch with 5 results from five one-minute videos costs $0.095 in source-transcript events before startup.

`maxChargeUsd` excludes startup and platform usage. Apify's own maximum-total-charge setting also limits events. Videos exceeding the duration limit are skipped rather than silently shortened. Processing is sequential to bound memory and costs. A $2 owner-provider reservation limit per run includes failed requests; a provider budget stop can leave work unprocessed.

No transcript row or value charge is created for known unavailable videos, no audio, no recognized speech, a slideshow or missing captions in captions mode. The startup event may still apply; platform usage is paid by the creator. Files are saved before row delivery and billing. Interrupted delivery stops automatic recharging and requires inspection of saved files and event charges.

### API example

After private deployment and approval of cloud tests, use your own Apify token. The response contains run and storage identifiers; poll completion and retrieve the dataset and summary.

```bash
curl --request POST \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"videoUrls":["7534679152504376595"],"maxVideos":1,"maxChargeUsd":0.10}' \
  'https://api.apify.com/v2/acts/khadinakbar~douyin-transcripts-scraper/runs?maxTotalChargeUsd=0.11'
```

Use `defaultDatasetId` with Apify's dataset API. Export rows as JSON, CSV or Excel through Apify storage tools. Subtitle files are separate key-value-store records. Access and retention follow storage settings; links are not promised to last forever. No cross-user cache is used.

### AI-agent prompt

> Use khadinakbar/douyin-transcripts-scraper for spoken text from these public Douyin URLs. Retain source speech, request English only when needed and cap transcript events at $1. Read run outcome and dataset before summarizing. Report incomplete text, failed translation, provenance and export links. Use separate Douyin discovery tools to find videos.

Direct API use is intended. Hosted MCP discovery, exposed schemas, stateless execution and payment eligibility remain unverified for this private candidate.

### Best results and troubleshooting

Begin with one short, clearly spoken video you can currently open publicly. Use a direct URL if a stale share link fails. Choose `speech` to regenerate absent or unsuitable captions. Dialects, singing and noisy music can reduce recognition quality. Verify important quotes and editing timings against the source.

`VALID_EMPTY` records known skip reasons. `INVALID_INPUT` includes a correction hint. `PARTIAL` preserves results and reports failed or remaining work. `UPSTREAM_FAILED` and `CONFIG_ERROR` with no useful output honestly fail. Retry target-access failures later; configuration failures require owner attention. Reduce the batch or adjust universal duration budgets for limit-related skips. Reconcile interrupted billing instead of blindly replaying it.

### Builder's note and verification methodology

Post captions and music tracks are easy to confuse with speech. The adapters separate them, validate video identity, label transcript provenance, preserve null counts and verify translation cue alignment. More fields alone would not prove better transcript quality.

Research checked on 2026-10-14 against live Apify Actor pricing metadata found competitors with lower prices and others offering MP4 archiving. This candidate targets batch input, preserved source text, provenance, inclusive subtitle exports and plan-neutral limits. Cloud delivery is under active validation; same-job price and reliability targets are not yet met. No universal superiority claim is made.

### Public-data boundaries

Process public videos you are authorized to collect, transcribe and translate. Review platform terms, copyright, privacy and applicable law for your use. Restricted/private videos and credential-based login are outside scope. Temporary media is deleted after processing; transcript files remain in your run storage under its retention settings. Owner provider secrets are supplied through encrypted environment configuration and excluded from results and logs. This independent tool is not affiliated with Douyin, ByteDance or competing developers.

# Changelog

This Actor's version history is a separate document: https://apify.com/khadinakbar/douyin-transcripts-scraper/changelog.md

# Actor input Schema

## `videoUrls` (type: `array`):

Provide public Douyin video links, share text or numeric video IDs. Example: https://www.douyin.com/video/7534679152504376595. Supply 1–100 entries; canonical duplicates are removed. Creator profiles and keyword search belong in separate Douyin Actors.

## `maxVideos` (type: `integer`):

Set the maximum number of unique videos to process. Example: 20. Default 10; range 1–100. Remaining input videos are reported in the run summary.

## `targetLanguage` (type: `string`):

Choose an optional translation of the spoken transcript. Example: en for English. Original is the default and preserves the source speech. Both original and translated text are retained when translation succeeds.

## `transcriptMode` (type: `string`):

Choose native captions, speech recognition or automatic selection. Example: speech regenerates spoken text from the video audio. Auto tries source captions before speech recognition. Captions mode skips videos with no source subtitle track.

## `exportSubtitles` (type: `boolean`):

Export original and translated subtitles when available. Example: true. Enabled by default with no extra export event. TXT and full JSON exports are retained regardless of this switch.

## `includeWordTimestamps` (type: `boolean`):

Include word timings returned by speech recognition. Example: true. Disabled by default; native captions have cue timings only. Model estimated timing is not a human verified forced alignment.

## `responseFormat` (type: `string`):

Choose detailed or concise dataset rows. Example: concise limits transcript previews to 1500 characters and ten cues. Detailed is the default. Full transcripts remain in TXT and JSON exports in both modes.

## `maxDurationMinutes` (type: `integer`):

Skip videos longer than this duration. Example: 20 permits a twenty minute video. Default 10; range 1–30 minutes. This universal limit does not depend on the caller account plan.

## `maxTotalMinutes` (type: `integer`):

Cap total billed audio minutes across the batch. Example: 60. Default 30; range 1–300. Each video duration is rounded up to a whole minute before checking the remaining budget.

## `maxChargeUsd` (type: `number`):

Set a run budget for transcript and translation events. Example: 1.00. Default 5; range 0.001–100 USD, also limited by the platform max total charge. The platform synthetic start event and compute/proxy/storage usage are additional.

## `maxRunSeconds` (type: `integer`):

Set an overall execution deadline. Example: 300. Default 900; range 60–3600 seconds. A stopped batch preserves delivered transcripts and reports remaining videos.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.douyin.com/video/7534679152504376595"
  ],
  "maxVideos": 10,
  "targetLanguage": "original",
  "transcriptMode": "auto",
  "exportSubtitles": true,
  "includeWordTimestamps": true,
  "responseFormat": "detailed",
  "maxDurationMinutes": 10,
  "maxTotalMinutes": 30,
  "maxChargeUsd": 5,
  "maxRunSeconds": 900
}
```

# Actor output Schema

## `results` (type: `string`):

Read the transcript dataset. Concise mode returns previews and full export links.

## `summary` (type: `string`):

Read the terminal outcome, failures, skip reasons, remaining inputs and charged events.

## `exports` (type: `string`):

List source and translated transcript files.

## `output` (type: `string`):

Read matching final outcome and result counts.

# 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 = {
    "videoUrls": [
        "https://www.douyin.com/video/7534679152504376595"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/douyin-transcripts-scraper").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 = { "videoUrls": ["https://www.douyin.com/video/7534679152504376595"] }

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/douyin-transcripts-scraper").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 '{
  "videoUrls": [
    "https://www.douyin.com/video/7534679152504376595"
  ]
}' |
apify call khadinakbar/douyin-transcripts-scraper --silent --output-dataset

```

## MCP server setup

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

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/8YtB8Z09Rm3xkPZRy/builds/GBU2iadFgEeZY8b3j/openapi.json