Esta página todavía solo está disponible en chino. La navegación y los menús ya aparecen en español.

音频 API 指南

使用 POST /v1/audio/speech 将文字转换成语音。请求是 JSON，默认成功响应是音频字节，不是 Chat 消息、JSON 下载地址或异步任务。若要让模型理解音频并输出文字，应选择支持音频输入的文本接口与模型。

准备模型、音色与格式

选择具有音频 API 映射的公共模型，替换示例 YOUR_MODEL_ID 和 REPLACE_WITH_SUPPORTED_VOICE。音色不是跨服务商通用值，必须使用所选模型支持的名称或自定义音色 ID。将 INONEAPI_API_KEY 设为服务端环境变量。

字段用法
model必填公共模型 ID。
input必填非空朗读文本；不会自动分段、截断或转换 SSML。
voice必填非空音色名，或模型支持的 {"id":"voice_123"} 对象。
instructions可选语气或情绪描述，只对支持该参数的模型有效。
response_format默认 mp3；必须匹配模型或固定格式映射。
speed可选 0.25–4；服务商可能有更严格范围。
stream_format默认 audio；sse 仅限支持它的原生渠道。

生成并保存音频

Node.js 20+ 示例先检查 HTTP 状态，再分块写入临时文件；成功接收后改名，失败时清理半成品。此单任务示例使用固定文件名，并发应用应为每次请求分配独立临时路径。

curl  https://api.inoneapi.com/v1/audio/speech \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","input":"Welcome to InOneAPI.","voice":"REPLACE_WITH_SUPPORTED_VOICE","response_format":"mp3"}' \
  --output speech.mp3

cURL 的 --fail-with-body 可能把错误 JSON 写到 speech.mp3，必须检查退出状态后再播放。成功二进制响应不能调用 response.json()。下载后的时长和编码以实际内容为准。

选择输出格式

格式常见 MIME使用注意
mp3audio/mpeg默认格式，适合常见播放器。
opusaudio/ogg确认播放器支持 Ogg Opus。
aacaudio/aac封装兼容性由服务商与播放器决定。
flacaudio/flac无损格式，文件通常较大。
wavaudio/wav带容器头，采样参数以结果为准。
pcmapplication/octet-stream裸采样数据；需明确采样率、位深、声道与端序。

网关不负责转码；将 .pcm 改成 .wav 不会添加 WAV 头。固定格式 Base64 映射只接受所配置的格式，省略 response_format 按 mp3 校验，不能假设自动匹配。

使用参考音频

只有明确支持参考音频的模型及映射才能使用以下扩展。先上传素材，使用同一 Key 调用语音接口：

{
  "model": "YOUR_MODEL_ID",
  "input": "Welcome to InOneAPI.",
  "voice": "REPLACE_WITH_SUPPORTED_VOICE",
  "response_format": "mp3",
  "input_references": [
    {
      "type": "audio",
      "role": "reference",
      "source": {
        "type": "file",
        "file_id": "file_ioa_0123456789abcdef0123456789abcdef"
      }
    }
  ]
}

input_references 不属于 OpenAI 原生 Speech 参数，也不自动提供声音克隆、音色注册或音频转写。type 必须匹配实际 audio，role 需要映射支持；网关将文件转换成签名 URL 后保留 role。原有 input、voice、model 仍必填。

流式传输

普通 stream_format: audio 返回音频字节流，HTTP 分块不等于 SSE，也不保证逐字节即时转发。上面的保存示例适用于该模式。

原生渠道支持时可以使用 stream_format: sse，客户端需按该服务商的事件格式解析音频片段，不能把 SSE 文本直接写成 MP3。不要发送 Chat 风格的 stream 字段。DSL 转换和 Base64 音频提取不支持 SSE，会返回 PROTOCOL_STREAM_UNSUPPORTED。

限制与错误处理

400 INVALID_REQUEST_BODY 检查必填字段、格式与 speed；AUDIO_FORMAT_UNSUPPORTED 检查固定格式映射；502 PROTOCOL_RESPONSE_TRANSFORM_FAILED 检查上游 JSON/Base64 或缓冲上限。401/403 检查权限，402 检查余额和预算，429 遵循 Retry-After 并限制并发。

此接口不提供音频转写、翻译、Realtime、任务查询或自动拼接。长文本应根据模型限制由应用分段，并处理音色一致性与拼接。超时可能已经生成和计费，不要无限重试。记录 X-Gateway-Trace-ID，避免记录敏感朗读文本，向最终用户明确说明音频由 AI 生成。

POST /v1/audio/speech · POST /v1/files · 文本指南

Audio · Documentación · InOneAPI