为你的应用接入视频字幕

按指定语言获取现有字幕，并看清实际返回的语言和字幕类型。

免费套餐每月 1,000 次请求，不用银行卡，不发验证邮件。

语言按你写的顺序找，不静默换语言。
每次返回都写明实际语言和字幕类型。
失败会说明原因；服务故障不会被说成“没有字幕”。

示例示例响应 · 数据是编的，不是真实视频

GET /v1/youtube/videos/VIDEO_ID/transcript
    ?lang=en-US,en&kind=manual,auto

HTTP 200
{
  "data": {
    "requested": { "lang": ["en-US","en"] },
    "delivered": { "lang": "en", "kind": "auto", "source": "native" },
    "segments": [
      { "start": 0.0, "end": 2.4, "text": "Hello and welcome." },
      { "start": 2.4, "end": 5.1, "text": "…" }
    ]
  },
  "meta": { "request_id": "req_example_01", "billable": true, … }
}

没有 en-US，按你列的顺序用了下一个 en；返回里写明它是自动生成的轨。

GET /v1/youtube/videos/VIDEO_ID/transcript
    ?lang=ja&kind=manual,auto

HTTP 404
{
  "error": {
    "category": "verdict",
    "code": "language_not_available",
    "retryable": false,
    "details": { "available": [
      { "lang": "en", "kind": "manual" },
      { "lang": "es", "kind": "auto" } ] }
  },
  "meta": { "request_id": "req_example_02", "billable": false, … }
}

没有 ja。不会替你换成别的语言，并列出这个视频已有的语言。

GET /v1/youtube/videos/VIDEO_ID/transcript
    ?lang=en&kind=manual,auto

HTTP 503   Retry-After: 5
{
  "error": {
    "category": "transport",
    "code": "upstream_error",
    "retryable": true,
    "details": {}
  },
  "meta": { "request_id": "req_example_03", "billable": false, … }
}

这是临时故障，不是“没有字幕”。按 Retry-After 等待后重试。

三步发出第一次请求

1
注册，拿到 API 密钥
注册后密钥只显示一次，我们不存原文。放进环境变量，不要提交到仓库或贴进对话。
2
发出请求
写明哪个视频、按什么顺序找哪些语言、接受哪些轨类型。
3
读懂结果
看 delivered.lang 和 delivered.kind；出错时看 category、code 和 retryable。

export TEXTFROM_API_KEY="<your key>"
curl -G "https://api.textfrom.dev/v1/youtube/videos/VIDEO_ID/transcript" \
  -H "Authorization: Bearer $TEXTFROM_API_KEY" \
  --data-urlencode "lang=en-US,en" \
  --data-urlencode "kind=manual,auto" \
  --data-urlencode "format=json"

const res = await fetch(
  "https://api.textfrom.dev/v1/youtube/videos/VIDEO_ID/transcript" +
  "?lang=en-US,en&kind=manual,auto",
  { headers: { Authorization: `Bearer ${process.env.TEXTFROM_API_KEY}` } }
);
const body = await res.json();
if (res.ok) console.log(body.data.delivered, body.data.segments);
else console.log(body.error.code, body.error.retryable);

import os, requests

r = requests.get(
    "https://api.textfrom.dev/v1/youtube/videos/VIDEO_ID/transcript",
    params={"lang": "en-US,en", "kind": "manual,auto", "format": "json"},
    headers={"Authorization": f"Bearer {os.environ['TEXTFROM_API_KEY']}"},
    timeout=20,
)
body = r.json()
print(body["data"]["delivered"] if r.ok else body["error"]["code"])

将密钥放进环境变量。

免费套餐

公开试用期间只有一个套餐，免费。注册只要一个邮箱，马上拿到密钥。

Free 免费

每月请求1,000 次（UTC 月）
每月翻译100 次
每分钟请求5 次
有效密钥最多 3 把
费用免费，不用银行卡

免费注册

更高额度：规划中还没有付费套餐，也没有价格。

先知道这几件事

密钥只显示一次，我们不存原文，丢了没法再看。用邮箱验证码登录，撤销旧的再新建即可。
每次请求算 1 次，包括失败的请求；被限流拒绝的不算。
试用名额有限，所有人共用每天的总量。用完后接口返回 503，第二天恢复。
限额可能调整，以控制台“套餐”页显示的为准。
不保证一直可用，也不保证每个视频都有字幕。

能做什么，不做什么

现在能用的、不支持的，和规划中的。

能力	状态
列出视频的字幕轨语言代码、人工 / 自动 / 未知，以及能否翻译；来源没给的字段标“未知”，不猜。	可用
按你的语言顺序取字幕时间戳以秒为单位；支持 JSON、文本、SRT、VTT。	可用
清楚的错误错误类别、错误码、能否重试和请求 ID。	可用
翻译加 translate=zh（或其他语言）就能拿到机器翻译，免费，译文按段落合并。失败就报错，不会拿原文冒充译文。	支持
批量任务、SDK、语音转写	规划中
AI / Agent 接入（MCP）	规划中

给 AI 客户端用

MCP 还在规划中，没有实现。现成的提示词现在就能粘贴到 AI 客户端里用。

查看 AI / Agent 接入

示例提示词节选

When a request returns language_not_available,
tell the user which languages exist.
Do not pick another language for them.

A 503 with retryable=true is a temporary fault,
never “this video has no captions”.

Never ask the user to paste an API key into chat.

现在就能回答的问题

支持哪些视频和语言？: 不承诺所有视频、所有语言。取决于视频本身有没有字幕轨；没有时，返回里会列出实际有的。
收费吗？: 现在免费。免费套餐每月 1,000 次请求、每分钟 10 次、最多 5 把密钥。将来是否收费还没有决定。
能翻译吗？: 能：在取字幕的请求里加 translate=zh（或其他语言代码）。这是免费的机器翻译，质量有波动，字幕会按段落合并。没有字幕的视频不能靠它转写。
会存什么？: 邮箱、每把密钥的哈希和前 13 位、请求次数。不存字幕正文，也不存密钥原文。删除账号会立即删掉邮箱和密钥。
丢了密钥怎么办？: 旧密钥没法再看，但不用找：用注册邮箱收一个 6 位验证码登录，撤销丢失的那把，再新建一把。