Node.js SDK | transcript1 docs

在TypeScript或JavaScript服务端调用@transcript1/sdk，即可上传文件、提交转录，并等待转录文本生成。

处理社交平台链接，请使用SDK 1.1.0或更高版本。SDK 1.0.1只支持YouTube，其他平台的链接会在本地校验时被拒绝。用npm i @transcript1/sdk@latest更新。

这个版本要求针对最初支持的YouTube、X、TikTok、Instagram、Facebook和Bluesky。使用Twitch、Dailymotion、Pinterest、LinkedIn或Snapchat时，需要安装已加入对应平台支持的SDK版本，否则链接可能在本地校验时被拒绝。

安装SDK

npm i @transcript1/sdk

下文示例采用ES模块。可以保存为.mjs文件；使用.js文件时，在package.json中设置"type": "module"。Node 20.19+也支持require()，例如require('@transcript1/sdk')。

配置API密钥

先到“API keys”页面创建密钥。可通过服务器环境变量TRANSCRIPT1_API_KEY提供，也可在创建实例时传入apiKey：

import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
const other = new Transcript1({ apiKey: 't1_...' });

未提供密钥就创建实例，会抛出Transcript1Error，其错误码为missing_api_key。

提交转录并等待文本

调用transcribe(input, options)后，SDK会创建任务，等转录文本生成后再返回。返回类型为CompletedTranscription，包含status: 'completed'和transcript字段。任务失败或被取消时，Promise会被reject（拒绝）。

const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ');
console.log(done.transcript.text);
 
const file = await t1.transcribe('./interview.m4a', { speakers: true });

输入为Buffer或Uint8Array时，需要附上文件名，让SDK判断媒体类型：

import { readFile } from 'node:fs/promises';
 
const buffer = await readFile('./call.mp3');
const call = await t1.transcribe(buffer, { filename: 'call.mp3' });

SDK把以http://或https://开头的字符串当作链接，其他字符串当作文件路径。链接支持YouTube、X、TikTok、Instagram、Facebook、Bluesky、Twitch、Dailymotion、Pinterest、LinkedIn和Snapchat，也支持直接上传文件。后续新增的平台要求HTTPS。哪些公开录制内容可以提交、各平台支持哪些字幕，见来源与选项。文件不能超过2,000,000,000字节，扩展名支持mp3、wav、m4a、flac、ogg、opus、mp4、mov、webm和mkv。

帖子必须公开；同一个帖子有多个视频时，只转录第1个。平台由API根据链接自动判断，不需要自行识别。短链接的支持情况和其他限制见来源与选项。

除了路径和Buffer，也能传入Blob、ReadableStream<Uint8Array>，或逐块提供Uint8Array的异步可迭代对象。Blob需要指定filename，带文件名的File除外。流和异步可迭代对象必须同时提供filename和size，后者是以字节为单位的大小。

获取文本或字幕文件

用download(id, options)获取指定格式的转录文本。它会等转录完成，返回值始终是字符串；选择JSON时，拿到的是API返回的JSON原文，不是解析后的对象。

const text = await t1.download(done.id); // text is the default
const withTimes = await t1.download(done.id, { timestamps: true });
const srt = await t1.download(done.id, { format: 'srt' });
const vtt = await t1.download(done.id, { format: 'vtt' });
const json = await t1.download(done.id, { format: 'json' });

只有text支持timestamps: true。其他格式设置该选项，Promise会被reject（拒绝），错误码为invalid_input。如果任务失败或被取消，download返回的Promise也会被reject（拒绝）。

提交后稍后再取文本

不想等待转录完成，可用transcriptions.create先提交任务。输入为文件时，该调用仍会等上传结束后再返回。

const job = await t1.transcriptions.create('./long-interview.mp4');
const now = await t1.transcriptions.get(job.id);
const finished = await t1.transcriptions.get(job.id, { wait: true });

get默认立即返回任务的当前状态。加上wait: true，则等到状态变为completed、failed或canceled再返回。先检查finished.status，再读取转录文本。注意：与transcribe不同，任务失败或被取消不会让get返回的Promise被reject（拒绝）。

查询任务、删除任务和查看账号

for await (const item of t1.transcriptions.list({ status: 'completed', limit: 50 })) {
  console.log(item.id, item.created_at);
}
 
await t1.transcriptions.delete(job.id);
const account = await t1.account();
console.log(account.minutes.remaining);

迭代list时，SDK会按需翻页。可按status筛选，也可指定platform：youtube、x、tiktok、instagram、facebook、bluesky、twitch、dailymotion、pinterest、linkedin、snapchat或upload。limit表示每页数量，可设为1到100，API默认为20。返回对象沿用API的snake_case字段名。media_id只作为字符串使用，不要解析其中的内容。

对运行中的任务调用delete会取消任务；对已结束的任务调用，则会删除任务和转录文本。用account查询套餐、分钟余额和用量限制。

调用选项

创建实例时可传入apiKey、baseUrl、fetch和maxRetries。未指定baseUrl时，SDK会使用环境变量TRANSCRIPT1_API_URL；该变量也未设置时，使用https://api.transcript1.com。需要自定义网络请求时，传入自己的fetch实现。maxRetries可设为0到10的整数，默认2。

以下选项同时适用于transcribe和transcriptions.create：

选项	用法
`speakers`	开启说话人分离。
`language`	用`auto`自动识别（默认），或指定ISO 639-1语言代码。
`source`	链接支持`auto`或`stt`。YouTube、X、TikTok、Bluesky、Dailymotion和LinkedIn有可用字幕轨道时，也支持`captions`。
`fresh`	重新转录链接，不复用最近24小时内已有的转录。
`filename`	Buffer、未命名的Blob和流必须提供；也可用来覆盖原文件名。
`size`	流和异步可迭代对象必须提供，单位为字节。
`idempotencyKey`	不传时，每次调用都会生成新的UUID。
`onProgress`	通过回调监听进度事件。
`signal`	传入AbortSignal，用于中止本次调用。

transcriptions.get支持wait、includeWords、onProgress和signal。要获取逐词时间戳，设置includeWords: true；等待时的进度变化通过onProgress通知。

download支持format、timestamps和signal，list也支持signal。调用transcriptions.delete(id, options)或account(options)时，可在options参数中传入{ signal }。

监听上传和转录进度

在transcribe、transcriptions.create，或开启等待的transcriptions.get调用中，传入onProgress：

await t1.transcribe('./interview.m4a', {
  onProgress(event) {
    console.log(event);
  },
});

事件类型	事件内容
`upload`	`sent`为已上传大小，`total`为总大小，单位都是字节。
`status`	`status`表示当前任务状态。
`waiting_slot`	`retryAfter`表示多少秒后再次尝试获取可用的任务名额。
`reconnecting`	等待时每次连接中断都会触发1次，没有额外字段。

中止调用与取消任务

用AbortController创建AbortSignal并传入，即可中止调用。也可以用AbortSignal.timeout限制等待时间：

await t1.transcribe('https://youtu.be/dQw4w9WgXcQ', {
  signal: AbortSignal.timeout(10 * 60_000),
});

如果还没发出首个请求就中止，Promise会被reject（拒绝），错误码为aborted，不带任务id。上传过程中中止时，如果任务仍为awaiting_upload，SDK会先尝试删除它。随后Promise会被reject（拒绝），错误码为aborted，并在错误中附上任务id。

中止等待不等于取消转录，服务端任务仍会继续。可以取出错误中的transcriptionId，用transcriptions.get(id, { wait: true })接着等待。确实要取消任务时，调用transcriptions.delete(id)。

等待转录时，如果发生网络错误，或收到HTTP 429、500、502、503、504响应，SDK会持续重试，不受重试次数限制。重连间隔依次为2、4、8、16秒，之后为30秒。其他请求按maxRetries重试。创建任务时若没有可用的活跃任务名额，SDK也会等待并重试。需要限制整个调用的时长时，使用signal。

捕获并处理错误

API请求、转录任务和SDK本地错误，都可以通过捕获Transcript1Error来处理：

import { Transcript1Error } from '@transcript1/sdk';
 
try {
  await t1.transcribe('./call.mp3');
} catch (error) {
  if (error instanceof Transcript1Error) {
    console.error(error.code, error.message, error.transcriptionId);
  }
}

字段	说明
`message`	说明错误原因的文本。
`code`	可能是API错误码、任务失败码、`canceled`，或SDK本地错误码。
`status`	HTTP状态码。任务错误和本地错误不包含该字段。
`details`	API附带的错误信息，例如`minutes_needed`、`action_url`；默认是空对象。
`retryable`	重试是否可能成功，默认false。
`transcriptionId`	已有任务id时返回该id。
`transcription`	已获取转录对象时，返回最近获取的对象。

SDK本地错误码有missing_api_key、invalid_input、aborted、network_error和upload_token_refused。服务端返回的错误不是JSON时，错误码为http_<status>。

任务失败但没有提供错误对象时，SDK使用transcription_failed。如果取回的任务已完成，却没有转录文本，transcribe的Promise会被reject（拒绝），错误码为internal_error。API错误码见错误说明，响应字段见API参考。

运行环境要求

需要Node 20.19+。Bun和Deno通过node:兼容层应当也能运行，但自动化测试仅覆盖Node。SDK只供服务端使用，不要把API密钥放进浏览器代码。