Open API

API Documentation

Integrate TranscriptGenerate into your applications with our RESTful API. Create tasks, query results, and manage quotas programmatically.

Overview

Transcript Open API provides developers with video transcript extraction capabilities. Submit video URLs to extract transcripts asynchronously, then poll for results.

Workflow

Call the Create Task API with a video URL → get a taskId
Poll the Query Task API using the taskId → wait for status to become SUCCESS
Retrieve textContent from the query result

Authentication

All API endpoints require API Key and API Secret in the request headers for authentication.

Header	Description	Example
X-API-Key	Your API Key	ak_1a2b3c4d5e
X-API-Secret	Your API Secret	sk_9f8e7d6c5b

Keep your API Key and Secret secure. Never expose them in client-side code or public repositories.

Manage API Keys →

Authentication Failure Response

{
  "code": 401,
  "msg": "Missing API Key or Secret. Please include X-API-Key and X-API-Secret in the request headers."
}

🎬

Video Transcript Extraction

POST/transcript-api/v1/task/create

Create Transcript Task

Submit a video URL to create a transcript extraction task. Tasks are processed asynchronously; use the Query Task API to get results.

Request Body Parameters

Parameter	Type	Required	Description
workUrl	String	✅	Video URL (supports Douyin, Xiaohongshu, Kuaishou, etc.)
targetLanguage	String	❌	Target language code. Default "auto" (no translation). Specify a code like "en", "ja" to trigger translation (members only).

Request Example

curl -X POST "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/task/create" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b" \
  -H "Content-Type: application/json" \
  -d '{"workUrl": "https://v.douyin.com/xxxxxx"}'

Success Response

{
  "code": 200,
  "msg": "Task submitted",
  "data": {
    "taskId": "1893456789012345678",
    "status": "WAITING",
    "message": "Task submitted, processing in progress"
  }
}

Error Responses

Scenario	code	msg
Video URL is empty	500	Video URL cannot be empty
URL cannot be recognized	500	Failed to extract a valid platform URL from the input
Unsupported platform	500	This platform is not supported. Please try a different URL.
URL too long	500	The URL is too long. Please check and try again.
Non-professional member	601	API access is available for Professional members only. Please upgrade your plan.
Concurrency limit reached	601	Concurrency limit reached. Please wait for existing tasks to complete.
Insufficient quota	601	Insufficient quota remaining. Please upgrade your plan.
Non-member using translation	601	Multi-language translation is available for members only. Please upgrade your plan.

GET/transcript-api/v1/task/query?taskId={taskId}

Query Task Status & Result

Query task processing status by taskId. Returns the transcript content when the task is completed.

Parameters

Parameter	Type	Required	Description
taskId	String	✅	The task ID returned by Create Task

Request Example

curl -X GET "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/task/query?taskId=1893456789012345678" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b"

Processing Response

{
  "code": 200,
  "msg": "Success",
  "data": {
    "taskId": "1893456789012345678",
    "status": "WAITING",
    "errorMessage": null,
    "createTime": "2026-06-04 17:30:00"
  }
}

Completed Response

{
  "code": 200,
  "msg": "Success",
  "data": {
    "taskId": "1893456789012345678",
    "status": "SUCCESS",
    "errorMessage": "Video processing succeeded!",
    "textContent": "Full transcript extracted from the video...",
    "title": "Video Title",
    "platform": "DOUYIN",
    "duration": 60.5,
    "videoUrl": "https://example.com/video.mp4",
    "workUrl": "https://v.douyin.com/xxxxxx",
    "cover": "https://example.com/cover.jpg",
    "createTime": "2026-06-04 17:30:00"
  }
}

Task Failure Response

{
  "code": 200,
  "msg": "Success",
  "data": {
    "taskId": "1893456789012345678",
    "status": "FAILURE",
    "errorMessage": "Video processing failed!",
    "createTime": "2026-06-04 17:30:00"
  }
}

Response Fields

Field	Type	Description
taskId	String	Unique task identifier
status	String	Task status: WAITING, SUCCESS, or FAILURE
errorMessage	String	Status description message
textContent	String	Extracted transcript text (only on SUCCESS)
title	String	Video title (only on SUCCESS)
platform	String	Source platform: DOUYIN, XHS, KUAISHOU, etc.
duration	Number	Video duration in seconds
videoUrl	String	Video download URL
workUrl	String	Original video URL
cover	String	Video cover image URL
createTime	String	Task creation time

Error Responses

Scenario	code	msg
taskId is empty	500	Task ID cannot be empty
Task not found	500	Task not found
Accessing another user's task	500	You do not have permission to access this task

Recommended polling interval: 2-5 seconds. Most tasks complete within 10-30 seconds.

GET/transcript-api/v1/quota/usage

Query Quota Usage

Query the remaining video-to-text quota for your account.

Request Example

curl -X GET "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/quota/usage" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b"

Limited Quota Response

{
  "code": 200,
  "msg": "Success",
  "data": {
    "unlimited": false,
    "availableSeconds": 3600,
    "availableMinutes": "60.0",
    "totalSeconds": 7200,
    "totalMinutes": "120.0",
    "usedSeconds": 3600,
    "usedMinutes": "60.0",
    "deductionType": "monthly"
  }
}

Unlimited Quota Response

{
  "code": 200,
  "msg": "Success",
  "data": {
    "unlimited": true,
    "availableSeconds": -1,
    "availableMinutes": -1,
    "totalSeconds": -1,
    "usedSeconds": 0
  }
}

Response Fields

Field	Type	Description
unlimited	Boolean	Whether the quota is unlimited
availableSeconds	Number	Remaining available seconds (-1 means unlimited)
availableMinutes	String/Number	Remaining available minutes (-1 means unlimited)
totalSeconds	Number	Total quota in seconds (-1 means unlimited)
totalMinutes	String	Total quota in minutes
usedSeconds	Number	Used quota in seconds
usedMinutes	String	Used quota in minutes
deductionType	String	Reset cycle: monthly or daily

GET/transcript-api/v1/quota/concurrency

Query Concurrency

Query current concurrency usage and available slots for your account.

Request Example

curl -X GET "https://api.transcriptgenerate.com/open-gateway/transcript-api/v1/quota/concurrency" \
  -H "X-API-Key: ak_1a2b3c4d5e" \
  -H "X-API-Secret: sk_9f8e7d6c5b"

Success Response

{
  "code": 200,
  "msg": "Success",
  "data": {
    "currentConcurrency": 1,
    "maxConcurrency": 2,
    "availableConcurrency": 1,
    "canAddTask": true
  }
}

Response Fields

Field	Type	Description
currentConcurrency	Number	Currently running tasks
maxConcurrency	Number	Maximum allowed concurrent tasks
availableConcurrency	Number	Remaining available slots
canAddTask	Boolean	Whether a new task can be created

Status Codes

HTTP Status Codes

Code	Description
200	Request successful
401	Authentication failed (API Key/Secret missing or invalid)
500	Business logic error (see response msg field)

Business Status Codes (code field)

code	Description
200	Operation successful
401	Unauthorized (API Key/Secret missing or invalid)
500	System error (parameter validation failed, task not found, etc.)
601	Business warning (insufficient quota, insufficient permissions, concurrency limit reached, etc.)

Task Status Values

status	Description
WAITING	Processing (includes queuing, downloading, transcription stages)
SUCCESS	Completed, transcript is ready
FAILURE	Failed, check errorMessage for details

Supported Platforms

Platform	Code	URL Example
Douyin	DOUYIN	https://v.douyin.com/xxxxxx
Xiaohongshu	XHS	https://www.xiaohongshu.com/discovery/item/xxxxxx
Kuaishou	KUAISHOU	https://www.kuaishou.com/short-video/xxxxxx
More platforms	—	Continuously expanding

Supported Translation Languages

Specify the target language via the targetLanguage parameter (members only). Common language codes:

Language Code	Language
auto	No translation (default)
en	English
ja	Japanese
ko	Korean
zh	Chinese
fr	French
de	German
es	Spanish

Full language list available on the Transcript website.

Rate Limits

Limit	Description
Daily API call limit	Determined by your plan, check in user center
Concurrent task limit	Determined by your membership level
Recommended polling interval	2-5 seconds

Best Practices

Authentication failure (401) — Check that your API Key and Secret are correct, not expired or disabled
Concurrency limit reached — Query concurrency first, wait for existing tasks to complete before creating new ones
Insufficient quota — Query quota usage to confirm remaining balance, upgrade if necessary
Task failure — You can resubmit the task; if it fails repeatedly, contact support
Network timeout — Set a 30-second request timeout and implement exponential backoff retry

Python Example Code

Download all Python example scripts including create task, query task, quota usage, concurrency, and complete workflow.

Download Python Examples (.zip)