--- title: "面向视频和音频的转录 API" description: "用一个 REST API 把 YouTube、TikTok、Instagram、LinkedIn、Twitter/X 链接变成带时间戳的转录文本——优先使用字幕，没有字幕时由 AI 处理。" canonical: "https://transcript.im/zh-hans/api" markdown: "https://transcript.im/zh-hans/api.md" --- # 面向视频和音频的转录 API 用一个 REST API 把 YouTube、TikTok、Instagram、LinkedIn、Twitter/X 链接变成带时间戳的转录文本——优先使用字幕，没有字幕时由 AI 处理。 ## 链接 - [标准 HTML 页面](https://transcript.im/zh-hans/api) - [Markdown](https://transcript.im/zh-hans/api.md) transcript.im 把驱动产品的那条提取流水线以带版本的转录 API 开放出来。发送一个视频或音频 URL，就能拿回带时间戳的文本，格式为 JSON 或纯文本，平台由系统自动识别。已有字幕优先使用；视频没有字幕时，由 AI 转写音频，结果以异步方式返回。 - 一个 `url` 既接受完整链接也接受短链接，并自动识别 YouTube、TikTok、Instagram、LinkedIn 和 Twitter/X；YouTube 还支持直接传视频 id，已知来源时也可以用 `platform` 加 `externalId` 指定。 - 优先使用字幕；视频没有字幕时由 AI 转写人声，本地文件上传则一律走语音识别。 - `format=json` 返回带时间戳的分段，`format=text` 返回可直接粘贴的纯文本。 - 批量提取支持 URL 列表、播放列表和频道。 - 批量导出支持 txt、csv、json、srt、vtt、zip；已保存的转录可下载为 txt、srt、vtt、json 或 md。 - 已保存的转录存放在账户资料库中，YouTube 发现能力覆盖搜索、视频、频道、上传、播放列表和字幕。 - 完整契约以 OpenAPI 文档形式公开。 ## transcript.im API 能做什么 transcript.im API 把公开的视频或音频链接转化成带时间戳的转录文本，你的产品可以读取、存储、搜索，或送入模型。你发送一个 URL；API 解析平台，查找创作者已有的字幕轨，返回每一行都带时间戳的文字。当视频完全没有字幕时，API 不会停在错误上——它会改用 AI 转写人声，让同一个请求照样产出文本。 这一个行为正是转录提取 API 的意义所在：你不再需要把下载器、字幕抓取器和语音转文字服务拼在一起。API 为每个链接挑一条能用的最省成本路径，让时间戳与真实讲话对齐，并回报它最终使用的语言。已经存在的转录立即返回；需要语音识别的视频会作为任务移交出去，长时间录音不会一直占着你的请求。 - 一次请求，真实文本——解析一个链接，返回带时间戳的转录分段或纯文本。 - 字幕优先，AI 其次——有创作者字幕就用，没有就转写音频。 - ASR 默认异步——拿到 job id 后可以轮询长时间转写而不会阻塞。 - 感知语言——请求语言优先级，并读回 API 实际解析出的语言。 - 平台无关——调用方不需要知道视频托管在哪里。 ## 一个转录 API，覆盖五大平台 ### YouTube 任何公开的 YouTube 视频、Shorts 或直播录像都能转录，优先使用创作者字幕，字幕缺失时用 AI 转写。YouTube 也是拥有完整发现能力的平台——搜索、视频、频道、上传、播放列表和字幕——可与转录本身一起使用。一个频道的积压内容或一个播放列表会变成一批带时间戳的转录，而单个链接则返回可搜索的易读文本。 ### TikTok 公开 TikTok 视频的转录，优先使用字幕，语音识别作为兜底。粘贴视频链接，即可把口播内容读成干净、带时间戳的文本，方便二次利用、翻译或引用。同一次调用既能处理短视频也能处理较长的上传，所以趋势、教程和出镜口播都会以文本形式返回。 ### Instagram 公开 Instagram Reels 和视频帖子的转录。Instagram 没有可读取的字幕轨，因此提取走异步语音识别：提交链接、轮询任务，准备好后取回文本。这样即使平台从未把讲话发布成文字，一个 Reel 也能被引用和搜索。 ### LinkedIn 公开 LinkedIn 视频帖子的转录，优先使用字幕，语音识别作为兜底。结果带时间戳返回，因此一场演讲、一段产品短片或一次会议录像都会变成可搜索、可引用、可复用的文本。你可以从网络研讨会录像里提取论点，或把创始人的动态变成一份可编辑的草稿。 ### Twitter/X 公开 X 视频帖子的转录。X 没有可读取的字幕轨，因此提取走异步语音识别：提交链接、轮询任务，取回可搜索的带时间戳文本。你可以准确引用一段视频，或在帖子被编辑或删除前存档其口播内容。 ## 一次转录请求如何流转 一次调用就把链接或上传的文件从输入带到转录，API 会告诉你它走了哪条路径。 - 发送来源——提交 `url`，已知来源时传 `platform` 和 `externalId`，或以 `multipart/form-data` 把文件上传到同一个端点。 - 命中字幕——当视频带有你列表中的某种语言字幕时，转录会直接随响应返回。 - 处理语言未命中——当存在字幕但没有一条匹配你的列表时，请求会继续走 AI 转写并返回 `202` 和一个 job id；只有在调用方不允许使用语音识别时，才会返回带 `availableLanguages` 的 `404`。 - 强制或回退到 ASR——显式的 `asr` 条目、完全没有字幕轨的视频，或上传的文件，都会启动 ASR 任务并返回 job id。 - 轮询或订阅流——用 `GET /v1/transcript/job/{id}` 读取任务直到成功或失败，或订阅其 `/events` 流接收服务端推送的进度。任务查询即使任务失败也会返回 `200`，所以要根据 `status` 字段分支。 - 读取结果——完成的转录带有解析出的语言、时长、带时间戳的分段，以及按需返回的元数据，如标题、作者和发布日期。 - 安全重试——已经提取过的转录会直接从缓存返回，不再启动新任务，所以同一个来源可以再次请求。 - 先探查——`GET /v1/transcript/info` 会解析来源并列出它能提供的语言，供你在决定提取前判断。 由于同一个端点既服务缓存命中，也服务新的提取，你的集成不需要按来源分支：它始终发送来源，并对收到的状态作出反应。字幕命中直接返回转录，语言未命中继续走 AI 转写并返回 `202` 和 job id，真正不存在的资源或不被允许的兜底则返回 `404`。文本准备好后，每条路径都返回同一种转录结构。 ## 批量提取与导出 真实工作很少只处理一个视频，因此 API 接受 URL 列表、播放列表或频道形式的批量任务。每个批量都跟踪自己的统计——有多少条待处理、多少条成功、多少条失败——并按页返回条目，长频道不会以一整块巨大的负载到达。 - 三种批量形态——`POST /v1/batch` 根据你发送的请求体接受 URL 列表、播放列表或频道。 - 独立状态——失败的链接会被单独标记，绝不会丢弃批量中的其余条目；失败条目可以用 `/retry` 重试。 - 分页条目——用 `GET /v1/batch/{batchId}` 读取批量，然后跟随返回的 page token 获取剩余条目。 - 实时进度——每次轮询都返回更新后的计数，调用方可以展示长任务完成了多少。 - 按你的格式导出——从 `/export` 把完成的批量下载为 `txt`、`csv`、`json`、`srt`、`vtt` 或 `zip`。 对字幕流水线来说，`srt` 和 `vtt` 导出可以直接放进编辑器或播放器。对归档来说，`csv`、`json` 和 `zip` 让整座录像库作为一个语料可供搜索。这些格式与单条转录的响应保持一致，所以能处理单条结果的调用方，已经知道如何读取批量。 ## 账户资料库中已保存的转录 提取与存储是两回事：转录一旦被保存，就成为账户资料库的一部分，而资料库正是你之后读取、搜索、下载和删除它的地方，无需重新执行提取。 - 列出已保存内容——`GET /v1/library/transcripts` 分页遍历账户的转录、批量记录和失败历史行，支持搜索、平台与语言筛选以及排序。 - 读取单条——`GET /v1/library/transcripts/{platform}/{externalId}` 按平台与外部 id 返回已保存的转录，或按你指定的语言返回。 - 下载——`/download` 路由把已保存的转录导出为 `txt`、`srt`、`vtt`、`json` 或 `md`。 - 相关内容——`/related` 路由列出同一频道下其他已保存条目。 - 删除——`DELETE` 把条目从资料库移除，不会动到别人的副本。 - 限定账户的读取——资料库请求只返回该账户保存的内容，绝不启动新的提取，所以回看一条已保存的转录是读取，而不是又一个任务。 ## 转录之外的 YouTube 发现能力 YouTube 是 API 还能回答转录周边问题的平台，使用与 YouTube Data API 相同的资源命名。 - 搜索——`GET /v1/youtube/search` 按查询找视频、频道或播放列表，返回游标分页结果。 - 视频——`GET /v1/youtube/videos` 返回视频详情，包括是否有可用字幕。 - 频道——`GET /v1/youtube/channels` 按 id 或 `@handle` 解析频道。 - 频道上传——`GET /v1/youtube/channels/{channelId}/videos` 遍历一个频道的上传。 - 播放列表条目——`GET /v1/youtube/playlists/{playlistId}/items` 遍历一个播放列表。 - 字幕——`GET /v1/youtube/captions` 返回视频的字幕轨元数据和字幕正文。它绝不启动语音识别任务：当它报告 `requiresAsync` 时，调用 `POST /v1/transcript` 来执行转写。 发现回答要转录什么，提取回答说了什么。把两者分开意味着你可以先搜索和枚举，再只把你选中的链接送进转录或批量请求。 ## 为生产环境而设计 接口面故意做得很小，服务真正在意的部分都有文档可依，而不是靠猜。 - 一个凭证——用 Bearer 令牌形式发送 API 密钥认证，或在脚本、服务器里用 `X-API-Key`。 - 带作用域的密钥——只授予调用方需要的作用域，`transcripts` 和 `batches` 分别覆盖提取与批量工作。 - 结构化错误——提取和校验失败返回带稳定 `code` 与可读 `message` 的错误对象；认证 (401) 和限流 (429) 响应使用更简单的扁平错误体。 - 可执行的限制——被限流的请求返回 `429` 和 `Retry-After`，成功响应会带 `X-RateLimit-*` 头，让客户端能正确退避。 - 公开的契约——完整的 OpenAPI 文档支撑这套 API，你可以生成客户端、模拟服务端，或用 schema 校验真实响应。 - 面向智能体的兄弟入口——如果你的调用方是 AI 客户端而不是服务，同一个账户和工具也可以通过 transcript.im MCP 服务器访问。 ## 相关工具 - [API 文档](/docs) - [OpenAPI 文档](/docs/openapi.json) - [MCP 服务器](/zh-hans/mcp) - [Agent Skills](/zh-hans/skills) - [YouTube 转录生成器](/zh-hans/youtube-transcript) - [YouTube 视频摘要工具](/zh-hans/youtube-video-summarizer) - [YouTube 字幕生成器](/zh-hans/youtube-subtitle-generator) - [YouTube 字幕下载器](/zh-hans/youtube-subtitle-downloader) - [YouTube 频道转录](/zh-hans/youtube-channel-transcript) - [YouTube 播放列表转录](/zh-hans/youtube-playlist-transcript) ## 转录 API 常见问题 ### transcript.im API 是什么？ transcript.im API 是一个 REST 接口，把公开的视频或音频链接转化成带时间戳的转录文本，优先使用已有字幕，视频没有字幕时使用 AI 转写。 ### transcript.im API 支持哪些平台？ 它会从你发送的链接识别平台，提取 YouTube、TikTok、Instagram、LinkedIn 和 Twitter/X 的转录。YouTube、TikTok 和 LinkedIn 优先使用字幕，以语音识别作为兜底；Instagram 和 X 没有字幕轨，会直接走语音识别。 ### 视频没有字幕时会怎样？ 当视频完全没有字幕轨时，API 会启动 ASR 任务并返回 job id；你轮询该任务直到转录准备好，所以请求不会因语音识别而阻塞。 ### 可以转录本地的音频或视频文件吗？ 可以。`POST /v1/transcript` 接受带 `file` 部分的 `multipart/form-data` 请求体，用它替代 URL。上传的文件会直接走语音识别，因此返回 `202` 任务——如果在等待预算内完成，则返回 `200` 结果。 ### transcript.im API 能在返回文本的同时带上时间戳吗？ 可以。JSON 响应带有带时间戳的分段，文本响应可以保留每行的时间戳前缀，因此你可以回到某句话被说出的那一刻。 ### 如何请求特定语言的转录？ 发送一个逗号分隔的语言优先级列表，包含 `asr` 和 `asr-` 条目。字幕命中会直接返回；当存在字幕但没有一条匹配列表时，请求会继续走 AI 转写并返回 `202` 任务，只有在不允许使用语音识别时，才会返回带可用语言的 `404`。 ### 怎样知道异步转录已经准备好？ 用同一个凭证轮询 `GET /v1/transcript/job/{id}`，直到它报告成功或失败，或订阅 `GET /v1/transcript/job/{id}/events` 接收服务端推送的更新。任务查询在任务失败时也返回 `200`，所以请读取 `status` 和 `error` 字段，而不是 HTTP 状态码。 ### transcript.im API 支持批量提取吗？ 支持。一个批量接受 URL 列表、播放列表或频道，跟踪每个条目的状态，并按页返回条目。 ### 可以下载哪些导出格式？ 完成的批量可导出为 `txt`、`csv`、`json`、`srt`、`vtt` 或 `zip`；单条已保存的转录可下载为 `txt`、`srt`、`vtt`、`json` 或 `md`。 ### 已保存的转录放在哪里？ 账户资料库就是已保存的转录和批量记录所在之处，位于 `/v1/library` 下。它提供列出、读取、下载、相关和删除路由，读取限定在账户范围内，绝不启动新的提取。 ### YouTube 字幕端点返回什么？ `GET /v1/youtube/captions` 返回视频的字幕轨元数据以及字幕正文。它绝不启动语音识别任务；当它报告 `requiresAsync` 时，调用 `POST /v1/transcript` 来执行转写。 ### transcript.im API 如何报告错误和限流？ 提取和校验错误使用带 `code` 和 `message` 的对象；认证返回扁平的 `401`，限流返回扁平的 `429`，并带 `Retry-After` 和 `X-RateLimit-*` 头，让客户端能正确退避。 ## 把转录加入你的产品 创建一个 API 密钥，发送一个视频链接或本地文件，然后以 JSON 或纯文本读回转录。 - [创建 API 密钥](/app/account/api-keys) - [阅读文档](/docs)