文本转语音 API 教程：gpt-4o-mini-tts 与 tts-1-hd

选择 TTS 模型

模型	适用场景	输入限制	核验价格
`gpt-4o-mini-tts`	用 `instructions` 控制表达	4,096 字符；模型上限 2,000 tokens	文本输入 $0.60 / 1M tokens + 音频输出 $12 / 1M audio tokens
`tts-1-hd`	传统高清 TTS 兼容	4,096 字符	$30 / 1M 字符

生成的声音是 AI 合成语音。对外发布或播放时，应向最终用户明确披露。

gpt-4o-mini-tts

instructions 可描述语气、速度、口音或情绪。响应是音频字节，因此 cURL 必须使用 --output。

cURL · 生成 MP3

curl https://api-models.com/v1/audio/speech \
  -H "Authorization: Bearer $API_MODELS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "input": "您的订单已经可以取货。",
    "voice": "marin",
    "instructions": "语气温暖，发音清晰，语速舒缓。",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3

Python · requests

import os
import requests

response = requests.post(
    "https://api-models.com/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['API_MODELS_KEY']}"},
    json={
        "model": "gpt-4o-mini-tts",
        "input": "您的订单已经可以取货。",
        "voice": "marin",
        "instructions": "语气温暖，发音清晰，语速舒缓。",
        "response_format": "mp3",
    },
    timeout=120,
)
response.raise_for_status()
open("speech.mp3", "wb").write(response.content)

Node.js · fetch

import { writeFile } from "node:fs/promises";

const response = await fetch("https://api-models.com/v1/audio/speech", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_MODELS_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "gpt-4o-mini-tts", input: "您的订单已经可以取货。", voice: "marin", instructions: "语气温暖，发音清晰。", response_format: "mp3" }),
});
if (!response.ok) throw new Error(await response.text());
await writeFile("speech.mp3", Buffer.from(await response.arrayBuffer()));

tts-1-hd

使用相同端点，但不要传 instructions。当前上游建议使用兼容音色 alloy、echo、fable、onyx、nova、shimmer；其中 nova 和 alloy 已做线上请求验证。

cURL · 输出 WAV

curl https://api-models.com/v1/audio/speech \
  -H "Authorization: Bearer $API_MODELS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1-hd","input":"高清兼容语音示例。","voice":"nova","response_format":"wav","speed":0.9}' \
  --output speech.wav

参数与输出格式

字段	要求	说明
`model`	必填	两个精确模型 ID 之一
`input`	必填	最多 4,096 字符
`voice`	必填	必须与所选模型兼容
`instructions`	仅 gpt-4o-mini-tts	tts-1-hd 不支持
`response_format`	可选	`mp3`、`opus`、`aac`、`flac`、`wav`、`pcm`
`speed`	可选	0.25–4.0，默认 1.0

当前网关只公开普通二进制响应。不要添加 stream_format=sse，它不在已验证的兼容范围内。

常见问题

现象	处理
提示聊天接口错误	改用 `/v1/audio/speech`
音频为空或损坏	按二进制保存，写文件前检查 HTTP 状态
音色不兼容	tts-1-hd 使用上文列出的兼容音色
instructions 被拒绝	从 tts-1-hd 请求中移除