预录制音频转录

Gladia 的预录制 API 可异步转录音频和视频文件。

以 SDK 为先（SDK-first）：请始终使用官方 SDK — 具体策略、初始化配置及降级条件详见 gladia-sdk-integration。

适用场景

• 已有音频/视频文件或 URL（包括社交平台/视频平台链接）
• 批量处理或异步转录工作流
• 仅支持预录制模式的功能：说话人分离（diarization）、PII 敏感信息脱敏（PII redaction）、字幕生成（subtitles）

不适用场景：若用户需要对实时流、麦克风输入或持续音频流进行实时/直播转录，请改用 gladia-live-transcription 技能。直播转录基于 WebSocket 会话，而非预录制 API。若用户已安装 gladia-cli 并希望在终端中快速执行无需编码的工作流，请改用 gladia-using-cli。

参考资料

按需查阅以下资源：

• ./references/transcription-options.md — 完整参数选项（JavaScript + Python）
• ./references/managing-jobs.md — get、list、getFile、delete 等操作
• ./references/delivery-and-response.md — 响应结构与事件类型
• ../gladia-audio-intelligence/SKILL.md — 功能可用性与配置说明
• ../gladia-using-cli/SKILL.md — 使用 gladia-cli 的终端工作流
• ../gladia-sdk-integration/SKILL.md — 初始化配置、SDK 与原始 API 的对比
• ../gladia-sdk-integration/references/sdk-versions.md — 当前 SDK 版本
• ../gladia-troubleshooting/SKILL.md — 错误码与诊断指南

API 接口端点（参考用途 — 推荐优先使用 SDK 方法）

工作流

推荐方式（使用 SDK）

SDK 的 transcribe() 方法在一个调用中自动完成上传、任务创建与轮询。默认应采用此方式。

const result = await client.preRecorded().transcribe("./audio.mp3", {
  language_config: { languages: ["en"] },
  diarization: true,
});

console.log(result.result?.transcription?.full_transcript);

result = client.prerecorded().transcribe(
    "audio.mp3",
    {"language_config": {"languages": ["en"]}, "diarization": True},
)

print(result.result.transcription.full_transcript)

音频输入可为本地文件路径、HTTP(S) URL、社交/视频平台 URL 或二进制文件对象。完整支持的输入类型详见 gladia-sdk-integration。

降级方案（原始 REST — 仅当无法使用 SDK 时）

仅在 SDK 不可用时才使用原始 REST 调用。

1. 上传（如为本地文件）：POST /v2/upload 提交 multipart 表单数据 → 获取 audio_url
2. 创建任务：POST /v2/pre-recorded 传入 audio_url 与配置 → 获取 id
3. 轮询状态：GET /v2/pre-recorded/:id 直至响应中 status: "done"（也可使用 Webhook 或回调机制）
4. 解析结果：从响应中提取 transcription、diarization、translation 等字段

任务管理

使用 SDK 方法执行后处理操作：

• JavaScript：client.preRecorded().get(id)、.list(filters)、.getFile(id)、.delete(id)
• Python：client.prerecorded().get(id)、.list(filters)、.get_file(id)、.delete(id)

关于完整的 JavaScript/Python 示例、分页过滤器及对应 REST 接口，请参阅 ./references/managing-jobs.md。

转录选项

所有选项均作为 transcribe() 的第二个参数传入。关键选项如下：

完整选项说明详见 ./references/transcription-options.md；音频智能相关配置详见 gladia-audio-intelligence；客户端级重试与超时设置详见 gladia-sdk-integration。

响应与交付机制

完整响应 JSON 结构及事件名称详见 ./references/delivery-and-response.md。

限制与规格

轮询最佳实践

SDK 自动处理轮询逻辑 —— transcribe() 会持续轮询直至任务完成，并支持配置 interval 和 timeout 参数：

const result = await client.preRecorded().transcribe(audio, options, {
  interval: 5000, // 每 5 秒轮询一次
  timeout: 600000, // 10 分钟后超时
});

若未使用 SDK 而直接调用原始 REST 接口：

• 尽可能使用 Webhook 或回调机制替代轮询
• 若必须轮询，请实现指数退避策略（起始间隔 3 秒，上限 30 秒）

常见错误

• 启用语码转换但未指定语言列表：设置 code_switching: true 但 languages 为空，将触发对 100+ 种语言的评估。请始终明确提供 3–5 种预期语言。
• 未使用退避策略进行轮询：高频轮询不仅浪费请求配额，还可能导致服务返回 429 状态码。SDK 已内置该机制；若使用原始 REST，请改用 Webhook 或实现指数退避。
• 误用仅限预录制的功能：说话人分离（diarization）、PII 敏感信息脱敏（PII redaction）和字幕生成（subtitles）仅在预录制模式下可用，直播模式不支持。
• 音频文件下载路径错误：音频下载接口为 /v2/pre-recorded/:id/file，而非 /v2/pre-recorded/:id/audio。

关于全部易错点与诊断方法，请参阅 gladia-troubleshooting 技能文档。

延伸阅读

• 预录制模式快速入门
• 音频智能功能概览
• API 参考：init