OpenAI TTS：生成语音文件

将文字转换为 MP3 等音频，并以二进制方式保存结果。

API Key application/json

功能与适用场景

适合播报、配音和语音提示。本页生成完整音频文件，应用面向用户时应清楚标识为合成语音。

支持模型与组合

gpt-4o-mini-tts；基础 tts-1 / tts-1-hd 也可按对应限制使用。不要把转写型号填入 speech。

第一步：设置鉴权

使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY。替换占位符，保留 Bearer 后的空格。无需厂商 API Key。

第二步：调用模型

POST https://top.qingyuntop.ai/v1/audio/speech

请求为 application/json。

Request

请求

/v1/audio/speech

Body

必填

Bodyobject

modelstring必填

必填，顶层。示例 gpt-4o-mini-tts；tts-1 / tts-1-hd 可用于对应基础合成。

inputstring必填

必填，顶层文本，最长4096字符。不要把提示词中的风格说明误算成单独的接口参数。；长度：0–4096

voicestring必填

必填，顶层，示例 alloy。可用音色随模型变化；基础通用音色有 alloy / echo / fable / onyx / nova / shimmer。；可选：alloy / echo / fable / onyx / nova / shimmer

response_formatstring

选填，默认 mp3，可选 mp3 / opus / aac / flac / wav / pcm。响应为对应音频字节，不是 JSON。；可选：mp3 / opus / aac / flac / wav / pcm；默认：mp3

示例mp3

speednumber

选填，0.25–4.0，默认1。影响合成语速。；默认：1；范围：0.25–4

示例1

instructionsstring

选填，用于 gpt-4o-mini-tts 的语气指导；tts-1 / tts-1-hd 不支持。

请求示例application/json

set -euo pipefail
python3 - <<'PY'
import base64
import json
from pathlib import Path

payload = json.loads(r'''{
  "model": "gpt-4o-mini-tts",
  "input": "欢迎使用青云TOP API。",
  "voice": "alloy",
  "response_format": "mp3"
}''')
encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
Path("request.json").write_bytes(encoded)
PY
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/audio/speech" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output speech.mp3

Response

返回响应 `200`

HTTP 响应

响应 200object

常见错误与参考

不要调用 response.json()。模型支持的音色不同，优先选择文中通用音色；风格 instructions 只用于支持的 TTS 型号。

401：检查本站 API Key 和 Bearer 格式；403：确认此 Key 可用该模型；429：遵循 Retry-After 退避。超时或 5xx 时保留请求标识和脱敏错误，避免盲目重发；其他通用排查见聊天接入总览。

OpenAI 公共 API 规范。