# 语音合成

<a id="speech-generation"></a>

AUDIO

<a id="语音合成"></a>

## 接口说明

使用 `POST /v1/audio/speech` 将文本转换为语音，按次计费；模型价格以模型目录和当前账户专属价格为准。默认返回 JSON 中的下载 URL，文件默认是 WAV。

```json
{
  "model": "gemini-3.8-flash-tts",
  "input": "你好，欢迎使用语音合成。",
  "voice": "Kore",
  "instructions": "用温暖自然的语气朗读",
  "response_format": "wav",
  "output_format": "url",
  "async": true
}
```

`model`、`input` 必填；`voice` 默认 Kore，可选音色见 `GET /v1/models` 的 `speech_voices`。`instructions` 控制朗读风格，`temperature` 可选，范围 0–2。

`response_format` 支持 `wav` 和 `pcm`；PCM 为 24kHz、16-bit、单声道。`output_format` 当前仅支持 `url`，不支持 MP3 或流式音频。

请求请携带 `Authorization: Bearer YOUR_API_KEY` 和固定的 `Idempotency-Key`。同一 Key、同一参数重复提交只创建一个任务；更换参数需使用新的请求标识。`async: true` 立即返回任务；省略时等待本次执行完成，未完成仍可能返回 HTTP 202。

```json
{
  "id": "evt-EXAMPLE",
  "model": "gemini-3.8-flash-tts",
  "status": "completed",
  "charged": 0.1,
  "data": [
    {
      "url": "https://y.junlistudio.com/media/EXAMPLE.wav",
      "mime_type": "audio/wav",
      "bytes": 48044,
      "expires_at": 1800000000
    }
  ]
}
```

返回的 `charged` 是积分；上例金额仅演示返回结构。使用原 API Key 调用 `GET /v1/audio/speech/{id}` 查询；未收到任务 ID 时用 `GET /v1/audio/speech?request_id=原Idempotency-Key` 找回。

状态包括 `in_progress`、`recovering`、`saving`、`completed`、`failed`、`uncertain` 和 `expired`。明确失败自动退款；断线、结果待确认时保留原任务与费用，不自动重新生成。下载恢复只处理已有结果；`uncertain` 请联系管理员核对原任务。URL 有效期见 `expires_at`，请及时下载；画布会将成功结果保存为当前浏览器的音频素材。