开发者文档

TokCaption API 文档

一个用于转写公开 TikTok 视频的 REST API；运行 AI 钩子分析和脚本改写；并大规模导出文字稿。使用 API 密钥进行身份验证，提交 URL，然后轮询获取结果。API 访问权限包含在 Pro 版中。

REST API · v2.1.0

TokCaption API

转写公开 TikTok 视频；运行 AI 钩子分析；并大规模导出——全部通过简洁的 JSON REST API 完成。使用 API 密钥验证身份，两次调用即可开始。更喜欢 AI 助手？同样的工具也可以作为 MCP 服务器用于 Claude 和 ChatGPT。

基础 URL

https://www.tokcaption.com/api/v1

鉴权

X-API-Key

接口端点

共 27 项，分为 6 组

身份验证

在设置 → API 密钥（Pro 版）中创建 API 密钥。每次请求都需通过 X-API-Key 请求头发送该密钥。控制台和移动端客户端也可以改用 Supabase JWT，以 Authorization: Bearer <jwt> 形式发送。请将密钥保存在服务端，切勿将其打包进浏览器代码中。

curl "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

快速入门

提交链接后，轮询任务直至完成。单个链接通常会直接完成——轮询前请先检查响应状态。

第 1 步 — 提交

使用你的 URL 调用 POST /api/v1/jobs。保存返回的 job_id。

第 2 步 — 轮询

每隔 1–2 秒请求 GET /api/v1/jobs/{jobId}，直到状态变为终态，然后读取 items[].transcript_text。

只有一个 URL，不想轮询？使用 GET /api/v1/quick 获取同步结果。

错误与速率限制

所有错误均返回相同的 JSON 结构。请根据 code 进行分支处理，而不是依据 HTTP 状态码或消息文本。收到 429 时，请遵循 Retry-After 请求头的指示。

错误响应结构

{
  "success": false,
  "error": "Free plan allows 5 transcripts per day.",
  "code": "QUOTA_EXCEEDED",
  "message": "Free plan allows 5 transcripts per day.",
  "error_info": {
    "code": "QUOTA_EXCEEDED",
    "message": "Free plan allows 5 transcripts per day.",
    "details": {
      "limit_type": "daily",
      "daily_limit": 5,
      "retry_after_seconds": 43200
    }
  },
  "details": {
    "limit_type": "daily",
    "daily_limit": 5,
    "retry_after_seconds": 43200
  }
}

所有错误代码

代码	HTTP	含义
AUTH_REQUIRED	401	凭证缺失或无效。请发送有效的 X-API-Key，或 Authorization: Bearer <jwt> 请求头。
VALIDATION_ERROR	400	请求正文、查询参数或路径无效。消息和详细信息会说明需要修正的内容。
PLAN_REQUIRED	403	此功能或选项需要 Pro 版套餐。升级即可解锁。
NOT_FOUND	404	任务、文字稿或资源未找到，或不属于你。
QUOTA_EXCEEDED	429	文字稿、智能体、下载或翻译配额已用完。免费版每日重置，Pro 版按计费周期重置。详见 details.reset_at。
RATE_LIMIT_EXCEEDED	429	短时间内提交、轮询或智能体请求过多。请遵守 Retry-After 响应头或 details.retry_after_seconds 中的等待时间。
DUPLICATE_REQUEST	409	idempotency_key 已被重复使用。原始请求已经执行。
TRANSLATION_LIMIT_EXCEEDED	429	已达到本月翻译配额上限。配额将在你的计费周期重置。
UPSTREAM_TEMPORARY_ERROR	503	TikTok 暂时屏蔽了该请求或触发了频率限制。请稍后退避重试。
SEGMENTS_UNAVAILABLE	400	此导出格式（srt/vtt）需要带时间戳的分段，但该文字稿没有分段数据。
INTERNAL_ERROR	500	服务器发生意外错误。请重试，如问题持续存在，请联系支持团队。

转写

提交公开 TikTok 链接进行转写，并跟踪任务进度。

POST/api/v1/jobs

提交转录任务

submit 上限

提交 1..N 个公开 TikTok 链接进行转写。批量数量受你的套餐限制；单个链接可能会直接返回完成的结果。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

当处理在同一次请求内完成时，单个 URL 可能返回 HTTP 200，并附带终态的 completed 或 failed 数据。
批量操作返回 HTTP 202，包含 job_id、汇总状态，以及 items 中每个条目的状态。
检查 items 数组以查看每个视频的状态：queued、processing、completed 或 failed。
免费版中设置 include_download_assets: true 将返回 PLAN_REQUIRED（403）。

请求体字段

`urls`必填 string[]	TikTok 视频链接。免费版批量上限为 5 个。
`output_language` string	目标文字稿语言（ISO 代码）。默认为 en。
`also_translate_to` string[]	要将文字稿翻译成的其他语言。
`allow_asr_fallback` boolean	当不存在字幕轨道时转写音频。默认为 false。
`include_download_assets` boolean	保存视频/封面资源以供下载。仅限 Pro 版。
`idempotency_key` string	去重键；重复使用时将返回原始任务。

成功响应 · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

即时单次成功

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

单次失败（无字幕）

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503

GET/api/v1/jobs

列出任务

按最新排序列出你的转写任务，支持游标分页。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

参数

`cursor` string (ISO date) · query	传入上一次返回的 next_cursor，即可翻到更早的数据。
`limit` integer · query	每页数量，1–50。默认为 20。
`status` string · query	按任务状态筛选（如 completed、processing、failed）。

成功响应

{
  "jobs": [
    {
      "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
      "created_at": "2026-06-23T10:02:11.000Z",
      "updated_at": "2026-06-23T10:02:48.000Z",
      "origin": "api",
      "status": "completed",
      "collection_name": null
    }
  ],
  "next_cursor": "2026-06-23T10:02:11.000Z"
}

错误

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/jobs/{jobId}

轮询任务状态

poll 上限

轮询任务直至其进入终态。返回汇总计数及每个条目的完整详情。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

终态任务状态包括 completed、partial 和 failed；任务内的单个条目状态可能有所不同。
已完成的条目包含 transcript_text、segments、translations、metadata 和 assets。
请以合理的间隔轮询（每 1–2 秒一次）。收到 HTTP 429 时，请遵循 retry_after_seconds 的等待时间。

参数

jobId必填

string · path

POST /api/v1/jobs 返回的任务 ID。

成功响应

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "processing",
  "total_items": 2,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "completed_at": "2026-03-14T08:33:14.000Z"
    },
    {
      "id": "tx_2",
      "transcript_id": "2448b6b8-7e07-46ef-96be-1f339abdb71f",
      "item_index": 1,
      "status": "processing"
    }
  ]
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404RATE_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/jobs/{jobId}/cancel

取消任务

取消任务中排队或处理中的条目。已释放的条目将退还配额。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs/b86f89f2-34f6-4b76-88f6-03c13c51b7a6/cancel" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

参数

jobId必填

string · path

要取消的任务 ID。

成功响应

{
  "cancelled_count": 3
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

GET/api/v1/quick

快速转录（单个链接）

submit 上限

提交单个链接并等待（最长约 55 秒）获取终态结果——这是任务接口的同步快捷方式。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/quick?url=https%3A%2F%2Fwww.tiktok.com%2F%40creator%2Fvideo%2F1234567890" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

若任务已进入终态（completed/failed），返回 HTTP 200；若等待时间结束仍在处理中，则返回 HTTP 202，此时请轮询 /api/v1/jobs/{jobId}。

参数

url必填

string · query

单个 TikTok 视频 URL。

成功响应

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed"
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/import/collection

批量导入

Prosubmit 上限

提交包含链接的 URL 列表或原始文本。免费版可提交 1 个链接；批量处理需要 Pro 版。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/import/collection" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en"}'

请求体字段

`urls` string[]	显式 URL 列表。请提供此项或文本。
`text` string	自由文本；TikTok 链接会被自动提取。
`output_language` string	目标文字稿语言。默认为 en。
`allow_asr_fallback` boolean	当不存在字幕时转写音频。默认为 false。

成功响应 · HTTP 202

{
  "total_urls_found": 5,
  "valid_urls": 4,
  "jobs_created": 1,
  "job_ids": [
    "b86f89f2-34f6-4b76-88f6-03c13c51b7a6"
  ],
  "invalid_urls": [
    "https://example.com/not-a-video"
  ]
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403RATE_LIMIT_EXCEEDED429UPSTREAM_TEMPORARY_ERROR503

文字稿

读取、搜索、导出已完成的文字稿及其资源，并下载相关文件。

GET/api/v1/history

列出 / 搜索文字稿

poll 上限

分页、可搜索的文字稿历史记录，支持按状态、文件夹和排序条件筛选。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/history?page=1" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

参数

`page` integer · query	从 1 开始的页码。默认为 1。
`limit` integer · query	每页数量，1–100。默认为 15。
`search` string · query	对文字稿内容和源 URL 进行全文匹配。
`status` string · query	completed \| failed \| all。默认为 all。
`order_by` string · query	created_at_desc \| created_at_asc \| completed_at_desc \| completed_at_asc。

成功响应

{
  "transcripts": [
    {
      "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "tiktok_video_id": "1234567890",
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "transcript_text": "Whenever I'm asked to teach a beginner...",
      "created_at": "2026-06-23T10:02:11.000Z",
      "completed_at": "2026-06-23T10:02:48.000Z",
      "folder": null
    }
  ],
  "page": 1,
  "limit": 15,
  "has_more": true,
  "total_count": 42,
  "total_pages": 3
}

错误

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}

获取文字稿

poll 上限

通过 ID 获取单个文字稿，包括完整文本、分段、译文、元数据和资源。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

参数

id必填

string · path

文字稿 ID。

成功响应

{
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "status": "completed",
  "input_url": "https://www.tiktok.com/@creator/video/1234567890",
  "output_language": "en",
  "source_language": "en",
  "selected_track_type": "creator",
  "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  },
  "metadata": {
    "author_username": "foodnetwork",
    "duration_seconds": 29
  },
  "completed_at": "2026-06-23T10:02:48.000Z"
}

错误

AUTH_REQUIRED401NOT_FOUND404VALIDATION_ERROR400

GET/api/v1/transcripts/{id}/export

导出文字稿

以 txt、srt、vtt、csv、json 或 pdf 格式下载单个文字稿。json 和 pdf 需要 Pro 版。

鉴权：API 密钥或 JWT请求：none响应：file download

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/export?format=srt" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

返回带有 Content-Disposition: attachment 的文件。format=json 返回 { id, text, segments, metadata }。
srt/vtt 需要带时间戳的分段，否则将返回 SEGMENTS_UNAVAILABLE。

参数

`id`必填 string · path	文字稿 ID。
`format` string · query	txt \| srt \| vtt \| csv \| json \| pdf。默认为 txt。
`language` string · query	导出译文，而非源语言。

成功响应

{
  "note": "Binary/text download. Example shows the format=json body.",
  "id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "text": "Whenever I'm asked to teach a beginner how to cook...",
  "segments": [
    {
      "start": 0,
      "end": 2.4,
      "text": "Whenever I'm asked to teach"
    }
  ],
  "metadata": {
    "author_username": "foodnetwork"
  }
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400

POST/api/v1/transcripts/export-batch

批量导出（ZIP）

将多个文字稿打包为 ZIP 一次性导出，可按 ID 列表或筛选条件选择。json/pdf 格式需要 Pro 版。

鉴权：API 密钥或 JWT请求：application/json响应：application/zip

curl -X POST "https://www.tokcaption.com/api/v1/transcripts/export-batch" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"srt","filters":{"status":"completed","orderBy":"created_at_desc"}}'

请求体字段

`format` string	txt \| srt \| vtt \| csv \| json \| pdf。默认为 txt。
`ids` string[]	显式文字稿 ID。省略则使用筛选条件。
`filters` object	{ search?, status?, folderId?, orderBy?, view? }。仅导出已完成的文字稿。

成功响应

{
  "note": "Returns a ZIP attachment named tokcaption-srt-export-<date>.zip."
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403NOT_FOUND404SEGMENTS_UNAVAILABLE400INTERNAL_ERROR500

DELETE/api/v1/transcripts/{id}

删除文字稿

永久删除文字稿、其已存储的资源以及文件夹关联。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X DELETE "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

参数

id必填

string · path

文字稿 ID。

成功响应

{
  "deleted": true
}

错误

AUTH_REQUIRED401NOT_FOUND404INTERNAL_ERROR500

GET/api/v1/transcripts/stats

文字稿统计

poll 上限

你账户的汇总统计数据。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/stats" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功响应

{
  "total": 944,
  "completed": 702,
  "failed": 212,
  "folders": 5
}

错误

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/transcripts/{id}/download/video

下载源视频

Pro

以 MP4 格式下载原始 TikTok 视频。仅限 Pro 版，并计入每月下载配额。

鉴权：API 密钥或 JWT请求：none响应：video/mp4

curl -X GET "https://www.tokcaption.com/api/v1/transcripts/85f4dd35-3bc5-413f-81a6-63e0b61722d2/download/video" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

以附件形式返回 video/mp4。仅在成功开始传输时才会消耗配额。

参数

id必填

string · path

文字稿 ID。

成功响应

{
  "note": "Binary video/mp4 attachment."
}

错误

AUTH_REQUIRED401PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404VALIDATION_ERROR400

AI 智能体

对文字稿运行钩子分析、脚本改写和传播力评分。（Pro）

POST/api/v1/agents/{agentType}

运行 AI 智能体

Proagent 上限

对已完成的文字稿排队执行 AI 分析。agentType 可选值为 hooks、script_rewrite、virality_explain、hook_score。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/agents/hooks" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2","input":{}}'

请求体字段

`transcript_id`必填 string	一份待分析的完整文字稿。
`input` object	可选的智能体专用参数。

参数

agentType必填

string · path

hooks | script_rewrite | virality_explain | hook_score。

成功响应 · HTTP 202

{
  "run_id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "queued"
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429NOT_FOUND404RATE_LIMIT_EXCEEDED429

GET/api/v1/agents/runs

列出智能体运行记录

按最新排序列出你的智能体运行记录，支持游标分页。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs?cursor=2026-06-23T10%3A00%3A00.000Z" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

参数

`cursor` string (ISO date) · query	传入 next_cursor 以返回上一页。
`limit` integer · query	每页数量，1–50。默认为 20。

成功响应

{
  "runs": [
    {
      "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "status": "completed",
      "agent_type": "hooks",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "created_at": "2026-06-23T10:05:00.000Z"
    }
  ],
  "next_cursor": null
}

错误

AUTH_REQUIRED401INTERNAL_ERROR500

GET/api/v1/agents/runs/{runId}

获取智能体运行记录

获取单次智能体运行结果，运行完成后包含其结构化输出。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/agents/runs/a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

参数

runId必填

string · path

智能体运行 ID。

成功响应

{
  "id": "a1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "agent_type": "hooks",
  "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
  "output": {
    "hooks": [
      "The first 3 seconds promise a payoff..."
    ]
  },
  "output_text": "The first 3 seconds promise a payoff...",
  "model": "claude-...",
  "completed_at": "2026-06-23T10:05:09.000Z"
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404

提取并翻译

底层基础接口：抓取元数据、翻译文本，以及对粘贴的输入进行分类。

POST/api/v1/extract/metadata

抓取元数据

解析 TikTok 链接，获取其元数据及最佳可用字幕轨道，无需创建任务。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/metadata" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@creator/video/1234567890"}'

请求体字段

`url`必填 string	一个 TikTok 视频 URL。
`output_language` string	首选字幕语言。默认为 en。

成功响应

{
  "normalized_url": "https://www.tiktok.com/@creator/video/1234567890",
  "source_language": "en",
  "selected_track_type": "creator",
  "subtitle_format": "webvtt",
  "metadata": {
    "author_username": "creator",
    "duration_seconds": 29
  }
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

POST/api/v1/extract/translate

翻译文本

将文字稿文本和/或带时间戳的分段翻译为一种或多种语言。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/extract/translate" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_text":"Whenever I'm asked to teach a beginner how to cook...","output_language":"es"}'

请求体字段

`full_text` string	待翻译的文本。请提供此项和/或 segments。
`segments` TranscriptSegment[]	需要翻译的带时间戳分段，翻译时保留时间信息。
`output_language` string	主要目标语言。默认为 en。
`additional_languages` string[]	其他目标语言。

成功响应

{
  "fullText": "Cada vez que me piden que enseñe a un principiante a cocinar...",
  "segments": [],
  "translations": {
    "es": {
      "full_text": "Cada vez que me piden..."
    }
  }
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400TRANSLATION_LIMIT_EXCEEDED429INTERNAL_ERROR500

POST/api/v1/workspace/resolve

解析粘贴的输入内容

将粘贴的文本 / @账号 / URL 分类为视频 URL、收藏预览或主页预览。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/workspace/resolve" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"@foodnetwork"}'

请求体字段

`text` string	粘贴的原始输入内容。与 urls 二选一提供。
`urls` string[]	显式 URL 列表。

成功响应

{
  "kind": "profile",
  "profile": {
    "username": "foodnetwork",
    "video_count": 1200
  }
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400UPSTREAM_TEMPORARY_ERROR503

文件夹

将文字稿整理到文件夹中。

GET/api/v1/folders

列出文件夹

列出你的文件夹及其项目数量。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功响应

{
  "folders": [
    {
      "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Cooking hooks",
      "created_at": "2026-06-23T10:00:00.000Z",
      "item_count": 12
    }
  ]
}

错误

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/folders

创建收藏夹

创建收藏夹，用于分组管理文字稿。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cooking hooks"}'

请求体字段

name必填

string

文件夹名称。

成功响应 · HTTP 201

{
  "id": "f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Cooking hooks",
  "created_at": "2026-06-23T10:00:00.000Z"
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

POST/api/v1/folders/{folderId}/items

将文字稿添加到收藏夹

将文字稿添加到收藏夹（幂等）。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/folders/f1f0ab70-7b6f-4f3b-9116-4135a6d8f53d/items" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript_id":"85f4dd35-3bc5-413f-81a6-63e0b61722d2"}'

请求体字段

transcript_id必填

string

要添加的文字稿。

参数

folderId必填

string · path

目标文件夹 ID。

成功响应 · HTTP 201

{
  "added": true
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400NOT_FOUND404INTERNAL_ERROR500

账户、密钥与账单

管理 API 密钥、查看套餐与配额，并提交反馈。

POST/api/v1/api-keys

创建 API 密钥

Pro

生成可用的实时 API 密钥。完整密钥仅显示一次，请妥善保存。仅限 Pro 版。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production server"}'

请求体字段

name必填

string

用于标识该密钥的标签。

成功响应 · HTTP 201

{
  "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "name": "Production server",
  "key_prefix": "tok_live_a1b2c3",
  "key": "tok_live_a1b2c3_d4e5f6g7h8i9j0k1l2m3n4o5",
  "created_at": "2026-06-23T10:00:00.000Z",
  "warning": "Save this key now — it will not be shown again."
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/api-keys

列出 API 密钥

Pro

按前缀列出你的有效密钥（密钥本身不会返回）。仅限 Pro 版。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/api-keys" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功响应

{
  "keys": [
    {
      "id": "k1f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
      "name": "Production server",
      "key_prefix": "tok_live_a1b2c3",
      "last_used_at": "2026-06-23T10:30:00.000Z",
      "created_at": "2026-06-23T10:00:00.000Z",
      "revoked_at": null
    }
  ]
}

错误

AUTH_REQUIRED401PLAN_REQUIRED403INTERNAL_ERROR500

GET/api/v1/plans

列出套餐

公开的有效套餐列表及其限额。无需认证。

鉴权：公开（无需认证）请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/plans"

成功响应

{
  "plans": [
    {
      "id": "free",
      "price_cents": 0,
      "billing_interval": "none",
      "free_daily_limit": 5,
      "agents_enabled": false,
      "downloads_enabled": false,
      "features": [
        "5 transcripts per day",
        "TXT & SRT export"
      ]
    },
    {
      "id": "pro_monthly",
      "price_cents": 900,
      "billing_interval": "month",
      "agents_enabled": true,
      "downloads_enabled": true,
      "features": [
        "Unlimited transcripts",
        "30 AI agent runs / month",
        "API access"
      ]
    }
  ]
}

错误

INTERNAL_ERROR500

GET/api/v1/billing/subscription

订阅与配额

您当前的套餐、订阅状态，以及文字稿、智能体、下载和翻译的实时用量/配额。

鉴权：API 密钥或 JWT请求：none响应：application/json

curl -X GET "https://www.tokcaption.com/api/v1/billing/subscription" \
  -H "X-API-Key: $TOKCAPTION_API_KEY"

成功响应

{
  "plan": {
    "id": "free",
    "price_cents": 0,
    "billing_interval": "none"
  },
  "subscription_status": null,
  "quota": {
    "transcripts": {
      "window": "daily",
      "limit": 5,
      "used": 2,
      "remaining": 3,
      "is_unlimited": false,
      "reset_at": "2026-06-24T00:00:00.000Z"
    },
    "agents": {
      "enabled": false,
      "limit": 0,
      "used": 0,
      "remaining": 0
    }
  }
}

错误

AUTH_REQUIRED401INTERNAL_ERROR500

POST/api/v1/feedback

提交反馈

提交产品反馈、错误报告或功能请求。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/feedback" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"feature","rating":5,"message":"Add a Zapier integration please!"}'

请求体字段

`category`必填 string	bug \| feature \| improvement \| other。
`message`必填 string	最多 2000 个字符。
`rating` integer \| null	可选，1–5 分评分。

成功响应

{
  "success": true
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400INTERNAL_ERROR500

Loading API documentation…

POST/api/v1/jobs

提交转录任务

submit 上限

提交 1..N 个公开 TikTok 链接进行转写。批量数量受你的套餐限制；单个链接可能会直接返回完成的结果。

鉴权：API 密钥或 JWT请求：application/json响应：application/json

curl -X POST "https://www.tokcaption.com/api/v1/jobs" \
  -H "X-API-Key: $TOKCAPTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@creator/video/1234567890","https://www.tiktok.com/@creator/video/0987654321"],"output_language":"en","also_translate_to":["es"],"allow_asr_fallback":false,"include_download_assets":false,"idempotency_key":"client-req-001"}'

当处理在同一次请求内完成时，单个 URL 可能返回 HTTP 200，并附带终态的 completed 或 failed 数据。
批量操作返回 HTTP 202，包含 job_id、汇总状态，以及 items 中每个条目的状态。
检查 items 数组以查看每个视频的状态：queued、processing、completed 或 failed。
免费版中设置 include_download_assets: true 将返回 PLAN_REQUIRED（403）。

请求体字段

`urls`必填 string[]	TikTok 视频链接。免费版批量上限为 5 个。
`output_language` string	目标文字稿语言（ISO 代码）。默认为 en。
`also_translate_to` string[]	要将文字稿翻译成的其他语言。
`allow_asr_fallback` boolean	当不存在字幕轨道时转写音频。默认为 false。
`include_download_assets` boolean	保存视频/封面资源以供下载。仅限 Pro 版。
`idempotency_key` string	去重键；重复使用时将返回原始任务。

成功响应 · HTTP 202

{
  "job_id": "b86f89f2-34f6-4b76-88f6-03c13c51b7a6",
  "status": "queued",
  "total_items": 2,
  "items": [
    {
      "id": "tx_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "input_url": "https://www.tiktok.com/@creator/video/1234567890",
      "status": "queued"
    }
  ]
}

即时单次成功

HTTP 200

{
  "job_id": "51f0ab70-7b6f-4f3b-9116-4135a6d8f53d",
  "status": "completed",
  "total_items": 1,
  "completed": 1,
  "failed": 0,
  "items": [
    {
      "id": "tx_single_1",
      "transcript_id": "85f4dd35-3bc5-413f-81a6-63e0b61722d2",
      "item_index": 0,
      "status": "completed",
      "output_language": "en",
      "source_language": "en",
      "selected_track_type": "creator",
      "transcript_text": "Whenever I'm asked to teach a beginner how to cook...",
      "metadata": {
        "author_username": "foodnetwork",
        "duration_seconds": 29
      },
      "completed_at": "2026-03-14T08:33:14.000Z"
    }
  ]
}

单次失败（无字幕）

HTTP 200

{
  "job_id": "8a0d6d7a-78f0-4ab0-8a8c-72f8f5184de8",
  "status": "failed",
  "total_items": 1,
  "completed": 0,
  "failed": 1,
  "items": [
    {
      "id": "tx_single_2",
      "transcript_id": "d40b2545-7c62-4bbb-a7e3-020c663f18a0",
      "item_index": 0,
      "status": "failed",
      "error_code": "NO_CAPTIONS_AVAILABLE",
      "error_message": "Captions are not available for this TikTok video."
    }
  ]
}

错误

AUTH_REQUIRED401VALIDATION_ERROR400PLAN_REQUIRED403QUOTA_EXCEEDED429RATE_LIMIT_EXCEEDED429DUPLICATE_REQUEST409UPSTREAM_TEMPORARY_ERROR503