Gladia 免费语音转写 API：注册送 50 欧元额度，可跑约 312 小时

Gladia 提供的是 REST 形式的语音转写接口，并不是对话补全模型，所以没有 /chat/completions 这类端点，也没有传统意义上的“模型名”要选。接口基址（base_url）形态为 https://api.gladia.io/v2，鉴权靠请求头 x-gladia-key，值就是上一步在控制台生成的 API Key；异步转写默认使用 Solaria-3 模型，具体可选项以官方文档和控制台显示为准。

1. 把密钥写进环境变量

先设置环境变量，后面的命令都直接引用它，避免密钥硬编码进脚本。

export GLADIA_API_KEY="你的 API Key 原文"

2. 上传本地音频，拿到可用地址

音频在本地时先调上传接口，响应里会返回一个可直接用于转写的文件地址（字段名以实际返回为准）。

curl -X POST https://api.gladia.io/v2/upload \
  -H "x-gladia-key: ${GLADIA_API_KEY}" \
  -F "audio=@./meeting.mp3"

3. 发起一次异步转写

异步转写是这份赠送额度最主要的用法。关键参数：audio_url 填上一步返回的文件地址；diarization 控制是否做说话人分离；language_config.languages 声明语言，中英混说时把多个语言代码一起给上，并开启 code_switching；callback_url 可选，填了之后服务端会在转写完成时主动回推结果，无需一直轮询。自定义词表、增强标点等开关同样在这个请求体里配置。

把请求体单独存成 request.json，避免命令行里拼长 JSON 出错：

{
  "audio_url": "AUDIO_URL_FROM_UPLOAD",
  "diarization": true,
  "language_config": {
    "languages": ["zh", "en"],
    "code_switching": true
  }
}

然后把文件作为请求体发出去：

curl -X POST https://api.gladia.io/v2/pre-recorded \
  -H "x-gladia-key: ${GLADIA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @request.json

4. 取回转写结果

创建任务的响应里会给出任务 id 和结果地址，把 id 存成变量后轮询即可；如果第 3 步配置了回调，就直接等回调推送。

export JOB_ID="创建任务返回的 id"
curl -X GET "https://api.gladia.io/v2/pre-recorded/${JOB_ID}" \
  -H "x-gladia-key: ${GLADIA_API_KEY}"

5. 实时转写

实时场景走 WebSocket 长连接，握手时带上同样的 API Key 以及采样率、编码等参数，端点路径和各参数写法以官方文档为准；自服务档实时并发默认 30，适合做字幕、会议实时纪要这类应用。

6. 额度耗尽与限流的典型表现和排查顺序

1. 401 或 403：先确认请求头 x-gladia-key 是否带对、密钥是否被删除，以及脚本里读到的环境变量是否为空。
2. 余额不足类报错：去控制台看余额和用量明细，50 欧元按 0.16 欧元/小时扣减，长音频批量跑很容易几天内见底，注意额度只有 1 年有效期。
3. 429 限流：多半是并发超过自服务档上限（异步 25、实时 30）或短时间请求过密，把并发压到上限以内，并在客户端加指数退避重试。
4. 任务长时间排队或转写失败：优先检查 audio_url 是否能被公网访问、文件格式和采样率是否受支持，外链不稳定时改成先走上传接口再转写。