venice-audio-transcription

Venice 转录（/audio/transcriptions）

POST /api/v1/audio/transcriptions 接收一个音频文件并返回文本。它兼容 OpenAI，使用 multipart/form-data——OpenAI SDK 的 audio.transcriptions.create() 无需修改即可使用。

方法	路径	身份验证	备注
POST	/api/v1/audio/transcriptions	Bearer 密钥或 x402（SIWX）	multipart/form-data，文件字段为 file，最大 25 MB。按音频秒数计费。

适用场景

• 需要为语音备忘录、会议、播客或短音频进行 STT（语音转文本）。
• 需要用于字幕或章节的词级／片段级时间戳。
• 想在 Venice 托管的 Parakeet、Whisper 系列模型、ElevenLabs Scribe 或 xAI STT 之间进行选择。

视频目前已没有转录端点——POST /video/transcriptions 已停用，会返回 410。请提取音轨并发送到此处，或通过支持视频的聊天模型 venice-chat 发起请求。

最简请求

curl https://api.venice.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "file=@./meeting.m4a" \
  -F "model=nvidia/parakeet-tdt-0.6b-v3" \
  -F "response_format=json" \
  -F "timestamps=false"

{ "text": "Alright everyone, let's kick off the meeting...", "duration": 184.2 }

设置 timestamps=true 后，JSON 还会包含一个 timestamps 对象（见下文）。

请求（multipart/form-data）

只会读取以下字段；表单中的其他内容都会被忽略。

字段	类型	默认值	备注
file	二进制	—	必填。 必须是实际文件部分（不能使用 base64）。支持：wav/wave、flac、m4a、aac、mp4、mp3、ogg/oga、webm。先通过扩展名／MIME 类型检查，再检查二进制签名。最大 25 MB。
model	字符串	—	请发送此字段。 OpenAPI 架构列出的默认值为 nvidia/parakeet-tdt-0.6b-v3，但实际上不会应用此默认值：省略 model 会返回 400 "model is required"。
response_format	json / text	json	仅支持这两种格式。text 会返回仅包含转录文本的 text/plain 响应正文。
timestamps	布尔值（表单字符串形式的 true/false）	false	在 JSON 响应中添加 timestamps。
language	字符串	—	ISO 639-1 提示（en、ja、……）。Whisper、Wizper、Scribe 和 xAI STT 会使用此字段；Parakeet 会忽略此字段（自动检测）。

响应

{
  "text": "…",
  "duration": 184.2,
  "timestamps": {
    "word":    [{ "word": "Alright", "start": 0.12, "end": 0.48 }],
    "segment": [{ "text": "Alright everyone…", "start": 0.12, "end": 4.9 }],
    "char":    [{ "char": "A", "start": 0.12, "end": 0.15 }]
  }
}

duration（秒）和 timestamps 均为可选项。具体返回哪些时间戳数组取决于所用模型：

模型	时间戳粒度
openai/whisper-large-v3	segment + word
fal-ai/wizper	segment
elevenlabs/scribe-v2	word
stt-xai-v1	word
nvidia/parakeet-tdt-0.6b-v3	可能包含 segment、word 和／或 char

模型

以下五个模型都列在实时 GET /models?type=asr 列表中。价格字段为 model_spec.pricing.per_audio_second.usd。

模型 ID	隐私级别	备注
nvidia/parakeet-tdt-0.6b-v3	private	由 Venice 托管，速度快。忽略 language。
openai/whisper-large-v3	private	支持多语言；提供 language 提示；支持片段级和词级时间戳。
fal-ai/wizper	private	Whisper v3 变体；提供 language 提示；支持片段级时间戳。
elevenlabs/scribe-v2	anonymized	提供 language 提示；支持词级时间戳。
stt-xai-v1	anonymized	提供 language 提示；支持词级时间戳。

使用 modelPrivacy: PRIVATE_ONLY 的密钥调用 anonymized 模型会收到 403（PRIVATE_TEXT 密钥在此处不受限制）。转录失败不会收费。

OpenAI SDK

import OpenAI from 'openai'
import fs from 'node:fs'

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: 'https://api.venice.ai/api/v1',
})

const out = await client.audio.transcriptions.create({
  file: fs.createReadStream('meeting.m4a'),
  model: 'openai/whisper-large-v3',
  response_format: 'json',
  language: 'en',
  // @ts-expect-error — Venice-specific extra, passes through multipart
  timestamps: true,
})

console.log(out.text)

长音频文件

服务端不会分块处理，上传文件大小上限为 25 MB。请在客户端拆分长录音（按静音处或固定时长分段），逐段转录，再结合偏移时间戳拼接结果。

ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3

错误

代码	含义
400	缺少 model、参数错误（例如 response_format 不是 json/text）、没有 file 部分（包括使用 JSON 请求体而非 multipart → "No audio file provided"）、扩展名/MIME 不受支持，或无法识别二进制签名。
401	身份验证失败。
402	余额不足。Bearer → {"error":"Insufficient USD or Diem balance…"}；如果达到密钥自身的上限，则为 `"API key USD
403	PRIVATE_ONLY 密钥调用 anonymized 模型，或受到区域限制。
404	未知 model。
413	文件大于 25 MB（{"code":"PAYLOAD_TOO_LARGE","error":"File exceeds the maximum allowed size of 25 MB."}）。
422	上游提供商无法处理音频（长度为零、无声、损坏、格式或语言不受支持，或提供商拒绝处理）。没有 suggested_prompt。
429	请求频率受限。
500	推理失败。
502	上游 ASR 暂时性故障 — {"error":"Audio transcription failed due to a temporary upstream error. Please retry."}（没有 code 字段）。使用退避策略重试。
503	模型暂时离线 — 使用抖动重试。

有关响应体格式和重试策略，请参阅 venice-errors。

注意事项

• 始终发送 model — 文档中所述的默认值不会生效。
• file 必须是实际的 multipart 文件部分。不支持 JSON + base64。
• 不支持 verbose_json、srt 或 vtt。如需字幕，请使用 response_format=json + timestamps=true，并自行渲染时间戳。text 会完全丢弃时间戳。
• 在基于 timestamps.word 与 timestamps.segment 构建功能之前，请先确认模型返回的粒度。
• 文件即使扩展名有效，如果二进制签名不是音频，也会被拒绝；请重新编码为标准配置文件（例如 MP3 44.1 kHz 或 16 kHz）。
• 遇到 429 时请采用退避策略；批量请求较多时应进行限流，不要一次性全部并行发送。