Lychee-Audio
返回产品
BASE URLhttps://lab.lycheeai.com.cnHTTPS
01

身份认证

所有服务端 API 请求使用 Bearer API Key。密钥与账户一一对应，应仅保存在服务端环境变量或密钥管理系统中，不能放入浏览器代码、公开仓库、日志或客户端安装包。

Authorization: Bearer lych_live_••••••••••••••••
访问条件

账户会自动获得默认 API Key。完成手机号验证后才能查看完整密钥；当前手机号绑定功能尚未正式开放。

02

快速开始

将密钥写入环境变量，发送 JSON 请求。生成通常需要数十秒，客户端超时时间建议设置为至少 130 秒。

  1. 1
    创建并获取密钥

    前往个人中心的 API 密钥区域。不要在前端页面中直接调用。

  2. 2
    组织声音 Prompt

    描述空间、角色、动作、对白、音乐与关键声音事件。

  3. 3
    保存返回音频

    响应中的 audio 为 Data URL，可直接解码为目标音频文件。

POST/api/audio/generate创建声音场景

根据 Prompt 和可选参考音频生成一段完整声音场景。每次请求只返回一个音频结果。

03

请求参数

请求体必须使用 application/json。未知字段会被忽略；建议只发送文档列出的字段。

promptrequired
string默认：—

完整的自然语言声音场景描述，长度为 8–1000 个字符。建议同时说明空间、人物、动作、对白、环境声、音乐和结束方式。

referenceAudio
object默认：null

参考音频对象。用于引导音色与说话风格；不提供时，模型仅根据 Prompt 创建声音场景。

settings
object默认：{}

输出音频与演绎参数。未提供的字段使用各自默认值，越界的数值会被限制到允许范围。

settings

format
stringmp3 | wav | ogg_opus · 默认 mp3

输出容器格式。MP3 适合网页分发；WAV 适合后期制作；OGG Opus 适合低带宽传输。

sampleRate
integer24000 | 44100 | 48000 · 默认 44100

输出采样率，单位 Hz。语音应用可选 24000；影视与音乐内容建议使用 44100 或 48000。

speechRate
integer-50 … 100 · 默认 0

对白语速调整。负值更慢，正值更快；仅影响语音演绎，不建议用它代替 Prompt 中的节奏描述。

loudnessRate
integer-50 … 100 · 默认 0

整体响度偏移。为避免削波，较高正值应配合后期响度检测使用。

pitchRate
integer-12 … 12 · 默认 0

音高偏移范围。用于轻微调整角色听感；大幅调整可能降低自然度。

04

参考音频

referenceAudio.data 接受纯 Base64 数据，不应包含 data:audio/...;base64, 前缀。建议使用清晰、无背景音乐的单人音频，长度不超过 30 秒，原始文件不超过 10 MB。

referenceAudio.namestring · optional

文件名或内部标识，仅用于请求侧记录，不参与声音生成。

referenceAudio.datastring · required

WAV、MP3、OGG 或 Opus 文件的纯 Base64 内容，编码字符串上限约 14 MB。

隐私提示

请确保你拥有参考声音的合法授权，不要上传未经许可的个人声音或敏感录音。

05

响应对象

成功时返回 JSON。audio 包含媒体类型和 Base64 内容；duration 为上游返回的音频时长，无法确定时为 null。

{
  "audio": "data:audio/mpeg;base64,//uQxAA...",
  "duration": 12.48
}
06

错误处理

非 2xx 响应均应作为失败处理。建议记录 HTTP 状态码和错误消息，并仅对 429、502、503 使用指数退避重试。

HTTP类型说明
400invalid_request

参数类型、Prompt 长度或参考音频格式不符合要求。

401invalid_api_key

缺少 API Key、格式错误、密钥无效或已撤销。

403access_not_ready

账户尚未完成访问条件，例如手机号验证。

429rate_limit_exceeded

同一 API Key 在 20 秒内重复发起生成请求。

502generation_failed

上游生成失败，或 Prompt 无法产生有效音频。

503service_unavailable

音频服务或密钥服务暂时未配置。

07

限流与安全

生成频率1 request / 20 seconds

以 API Key 为单位计算。收到 429 后至少等待 20 秒再重试。

请求超时125 seconds upstream

客户端建议设置 130–150 秒超时，避免服务端仍在生成时提前断开。

密钥存储Server-side only

使用环境变量或 KMS；发现泄露时应停止使用并联系管理员轮换。

传输协议HTTPS required

不要通过明文 HTTP、URL 查询参数或日志字段传递 API Key。