把声音，接入你的应用。

1. 01创建 API Key
2. 02获取可用声线
3. 03生成第一段语音

正在为 AI 助手接入语音能力？先阅读 AI 接入说明，了解产品能力、认证和调用边界。

第一段声音，从这里开始

先创建 API Key，再读取可用声线目录，最后发送一次语音合成请求。账户额度与计费以我的账户中显示的信息为准。

将 YOUR_VOICE_ID 替换为目录返回的可用声线 ID，环境变量 TTS_API_KEY 使用你自己的密钥。

curl --fail-with-body --show-error \
  --connect-timeout 10 \
  --max-time 235 \
  -X POST "https://www.sonelle.ai/api/v1/text-to-speech" \
  -H "Content-Type: application/json" \
  -H "Accept: audio/wav" \
  -H "X-API-Key: $TTS_API_KEY" \
  -d '{
    "voice_id": "YOUR_VOICE_ID",
    "generate_text": "Come a little closer. I want to tell you something.",
    "audio_format": "wav",
    "speed": 1.0,
    "request_id": "your-unique-request-id"
  }' \
  --output speech.wav

客户只需从运行时目录选择声线，LLM 模型会根据文本自动分析并匹配合适的表达风格。状态为 preview 的声音请在正式接入前试听确认效果。

鉴权

语音合成请求需要在请求头中携带 X-API-Key: sk_...。请在我的账户创建和管理 API Key，不要把完整密钥写入前端代码或公开仓库。

系统音色

GET /api/v1/tts/voices 使用 API Key，返回当前可用的系统音色与状态。

curl "https://www.sonelle.ai/api/v1/tts/voices" \
  -H "X-API-Key: $TTS_API_KEY"

可用声音与状态会更新；请使用接口响应， 不要从网页复制并长期保存一份静态 voice_id 表。只有接口返回且状态允许的声音才能调用。

语音合成

POST /api/v1/text-to-speech 在合成完成后一次返回音频。

成功响应的 body 是音频字节。响应头包含 X-Request-Id、X-Trace-Id、计费字符数和实际语速；WAV/PCM 还会返回采样率、声道和位深。

当前仅支持完整音频响应，不支持流式合成。

异步任务与音频下载

POST /api/v1/tts/jobs 立即返回任务；音频生成完成后保存到私有存储，通过 5 分钟有效的签名 URL 下载。创建请求必须携带 8–128 字符的 Idempotency-Key；异步任务接受 wav、mp3、opus 和 flac，不接受裸 PCM。

curl -X POST "https://www.sonelle.ai/api/v1/tts/jobs" \
  -H "X-API-Key: $TTS_API_KEY" \
  -H "Idempotency-Key: order-20260813-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "YOUR_VOICE_ID",
    "generate_text": "Hello from the asynchronous TTS API.",
    "audio_format": "wav"
  }'

使用 GET /api/v1/tts/jobs/{job_id} 查询状态；成功后访问 GET /api/v1/tts/jobs/{job_id}/audio，接口会返回 302 到签名下载地址。POST .../cancel 仅能取消排队或等待重试的任务。

DELETE /api/v1/tts/jobs/{job_id} 会停止签发新的下载链接，并将任务标记为 delete_pending。已签发的链接可能持续有效至到期；删除标记不代表存储中的音频已完成清理。

限流与重试

服务繁忙时可能返回 HTTP 429，请稍后重试并使用递增退避。request_id 仅用于请求追踪，不是计费或生成幂等键。遇到 HTTP 504、客户端超时或连接中断时，请先核对业务状态和余额，再决定是否重试。

音频格式

旧版 Safari/iOS 如无法播放 Ogg Opus，请改用 MP3；格式只影响交付编码，不改变文本计费。

API Key

请在我的账户创建、查看和吊销 API Key。完整密钥以 sk_ 开头，仅在创建时显示一次；吊销后不可恢复。

余额与流水

可在账单查看当前余额和消费流水。实际计费以账号配置与账单记录为准。

错误处理

请求失败时返回统一 JSON 格式：

{
  "error_code": 10001,
  "error_message": "参数错误",
  "succeed": false,
  "data": null
}