> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 音频转录与语音生成 API

> 用老张API把音频转成文字或字幕，或把文字生成语音文件：转录与语音生成的可用模型、语言与提示词、SRT 字幕、语气控制，以及 cURL 与 Python 示例。

老张API的音频接口沿用 OpenAI Audio API 格式，可以把音频转成文字，也可以把文字生成语音文件；两个接口都可以用 OpenAI SDK 调用。

| 项目 | 内容 |
| - | - |
| 音频转录 | `POST https://api.laozhang.ai/v1/audio/transcriptions`：以 multipart 表单上传音频文件，从响应的 `text` 读取文字 |
| 语音生成 | `POST https://api.laozhang.ai/v1/audio/speech`：发送文字，响应直接是音频文件 |
| 价格与计费方式 | 以[模型与价格总表](/models)为准 |

## 可用模型

2026 年 9 月 24 日公开价格配置中的音频模型如下，价格与计费方式以[模型与价格总表](/models)为准：

| 任务 | 模型 ID | 说明 |
| - | - | - |
| 音频转录 | `gpt-4o-transcribe`、`gpt-4o-mini-transcribe` | 标点和数字格式更规范，只支持 `json` 格式 |
| 音频转录 | `whisper-1` | 另外支持 SRT、VTT 字幕和带时间戳的 `verbose_json` |
| 语音生成 | `gpt-4o-mini-tts` | 可以用 `instructions` 控制语气和风格 |
| 语音生成 | `tts-1`、`tts-1-hd` | `tts-1` 延迟低，`tts-1-hd` 音质更高 |

单个文件的大小上限、支持的音频格式和可选音色，以 OpenAI 的[语音转文字](https://developers.openai.com/api/docs/guides/speech-to-text)和[文字转语音](https://developers.openai.com/api/docs/guides/text-to-speech)文档为准。

## 准备密钥

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，写入环境变量；使用 Python 示例时，先执行 `python -m pip install openai`。

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

## 音频转录

把要转录的音频放在当前目录，命名为 `audio.mp3`。下面使用 `whisper-1`，换成 `gpt-4o-mini-transcribe` 时只需修改 `model`。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 300 \
      "https://api.laozhang.ai/v1/audio/transcriptions" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -F "model=whisper-1" \
      -F "file=@audio.mp3"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=300.0,
        max_retries=0,
    )
    with open("audio.mp3", "rb") as audio_file:
        transcription = client.audio.transcriptions.create(
            model="whisper-1",
            file=audio_file,
        )
    print(transcription.text)
    ```
  </Tab>
</Tabs>

上传文件时注意：

* `-F "file=@audio.mp3"` 上传的是文件内容；只写文件名不会上传音频。
* 使用 `-F` 时让 cURL 自动设置 multipart 的 `Content-Type`，不要另加 `application/json`。

转录成功时返回 JSON，文字在 `text` 字段：

```json theme={null}
{"text": "你好，欢迎使用老张API。"}
```

### 指定语言和提示词

以下两个可选字段能提高转录准确度：

* `language`：音频的语言代码，例如中文 `zh`、英文 `en`。不填时模型自动识别。
* `prompt`：一段提示文字，写入产品名、人名等专有名词，帮助模型按这些写法输出。

```bash theme={null}
curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1/audio/transcriptions" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=gpt-4o-mini-transcribe" \
  -F "file=@audio.mp3" \
  -F "language=zh" \
  -F "prompt=老张API"
```

### 生成字幕和时间戳

`whisper-1` 可以用 `response_format` 直接输出字幕或分段时间戳：

| `response_format` | 返回内容 |
| - | - |
| `json` | 默认值，`{"text": "..."}` |
| `text` | 纯文本 |
| `srt`、`vtt` | 字幕文件内容，可直接保存为 `.srt` 或 `.vtt` |
| `verbose_json` | JSON，含 `language`、`duration` 和带起止时间的 `segments` |

以下示例把字幕保存为 `audio.srt`：

```bash theme={null}
curl --fail-with-body --max-time 300 \
  "https://api.laozhang.ai/v1/audio/transcriptions" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -F "model=whisper-1" \
  -F "file=@audio.mp3" \
  -F "response_format=srt" \
  -o audio.srt
```

GPT-4o 转录模型只支持 `json`，传入上表中的其他格式会报错。需要字幕或时间戳时使用 `whisper-1`。

## 语音生成

以下三个字段都必填：

* `model`：语音生成模型 ID；
* `voice`：音色名，例如 `alloy`；
* `input`：要朗读的文字。

响应默认是 MP3 音频，下面的示例把它保存为 `speech.mp3`。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 120 \
      "https://api.laozhang.ai/v1/audio/speech" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "tts-1",
        "voice": "alloy",
        "input": "你好，欢迎使用老张API。"
      }' \
      -o speech.mp3
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=120.0,
        max_retries=0,
    )
    with client.audio.speech.with_streaming_response.create(
        model="tts-1",
        voice="alloy",
        input="你好，欢迎使用老张API。",
    ) as response:
        response.stream_to_file("speech.mp3")
    print("已保存 speech.mp3")
    ```
  </Tab>
</Tabs>

用播放器打开 `speech.mp3` 即可试听。cURL 请求失败时，`speech.mp3` 里保存的是错误 JSON 而不是音频，用文本编辑器打开即可看到原因。

### 控制语气和输出格式

两个可选字段：

* `instructions`：仅 `gpt-4o-mini-tts` 支持，描述朗读的语气、语速和情绪。
* `response_format`：所有语音模型都支持，默认 `mp3`，也可以设为 `wav` 等格式，完整列表见 OpenAI 的[文字转语音](https://developers.openai.com/api/docs/guides/text-to-speech)文档。

```bash theme={null}
curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1/audio/speech" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "voice": "alloy",
    "input": "你好，欢迎使用老张API。",
    "instructions": "用轻快、热情的语气朗读。",
    "response_format": "wav"
  }' \
  -o speech.wav
```

## 常见问题

### 转录模型怎么选？

一般转录用 `gpt-4o-mini-transcribe`，单价低于 `gpt-4o-transcribe`，中英文的标点和数字都比较规范。需要 SRT、VTT 字幕或分段时间戳时用 `whisper-1`。对准确度要求更高时换成 `gpt-4o-transcribe`，单价见[模型与价格总表](/models)。

### 能转录中文吗？

能。三个转录模型都支持中文。建议加上 `language=zh`，并把专有名词写进 `prompt`，示例见[指定语言和提示词](#指定语言和提示词)。

### 能让模型听音频并回答问题吗？

转录接口只返回文字。需要模型直接理解音频，例如总结会议录音、判断说话人的意图，可以用 Gemini 模型的原生接口，见 [Gemini 协议：发送 PDF 和音频](/api-reference/gemini#发送-pdf-和音频)。GPT-6、GPT-5.6 等聊天模型不接受音频输入。

### 为什么保存的音频文件打不开？

请求失败时，cURL 的 `-o` 会把错误 JSON 写进音频文件。用文本编辑器打开该文件查看错误原因，或去掉 `-o` 重新请求。

另外检查文件扩展名是否与 `response_format` 一致，例如 WAV 格式要保存为 `.wav`。

## 相关文档

* [OpenAI 语音转文字指南](https://developers.openai.com/api/docs/guides/speech-to-text)
* [OpenAI 文字转语音指南](https://developers.openai.com/api/docs/guides/text-to-speech)
* [模型与价格总表](/models)
* [调用日志](/faq/call-logs)
* [数据与日志边界](/faq/data-security)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.