seed-audio-1.0 语音生成对接文档

更新日期：2026-10-12。

通过平台 POST /v1/audio/speech 调用 seed-audio-1.0，支持纯文本、文本加参考音频、文本加参考图片三种生成方式。接口同步等待生成完成，返回包含 Base64 音频和访问地址的平台 JSON，不支持 SSE 或 WebSocket 流式生成。

以下参数、请求示例及响应结构均适用于平台接口。

接入准备

调用方需要平台 API 令牌、平台服务地址，以及 seed-audio-1.0 的调用权限和可用额度。

以下示例使用 https://token.kelly.cloud 作为平台地址

项目	内容
请求方法	`POST`
请求路径	`/v1/audio/speech`
Content-Type	`application/json`
Authorization	`Bearer <平台 API 令牌>`
成功响应	HTTP 200，`application/json; charset=utf-8`
请求关联标识	响应头 `X-Request-Id`

使用平台签发的 API 令牌鉴权，无需传入登录 Cookie。

最小请求

{
  "model": "seed-audio-1.0",
  "text_prompt": "你好，这是一条语音测试。",
  "audio_config": {
    "format": "wav"
  }
}

将上面内容保存为 UTF-8 编码的 request.json。在 Windows PowerShell 中调用：

$env:PLATFORM_API_KEY = '替换为平台 API 令牌'
curl.exe --request POST "https://token.kelly.cloud/v1/audio/speech" --header "Authorization: Bearer $env:PLATFORM_API_KEY" --header "Content-Type: application/json" --data-binary "@request.json" --dump-header "response.headers.txt" --output "response.json"

response.json 是 JSON 响应，不能直接改名为 .wav 播放。需要解码 data.audio，或访问 data.url 获取音频文件。

Postman 配置相同：方法选 POST，Body 选 raw → JSON，Authorization 选 Bearer Token 并填写平台令牌。

请求参数

参数	类型	必填	说明
`model`	string	是	填写 `seed-audio-1.0`。若平台另设模型别名，以管理员提供的名称为准。
`text_prompt`	string	与 `input` 至少一项	待合成文字或音频生成描述，1～3000 个 Unicode 码点，包含空格和标点。
`input`	string	与 `text_prompt` 至少一项	兼容字段，与 `text_prompt` 等价；同时传入非空值时必须一致。建议只传 `text_prompt`。
`references`	array	否	参考资源，见下一节。不传或传空数组表示纯文本生成。
`audio_config`	object	否	当前仅支持其中的 `format`。
`audio_config.format`	string	否	`wav`、`mp3`、`pcm`、`ogg_opus`，默认 `wav`。
`response_format`	string	否	输出格式的兼容字段。与 `audio_config.format` 同时传入时须一致；`opus`、`ogg` 也可作为 `ogg_opus` 的别名。
`speed`	number	否	语速倍率，范围 0.5～2；1 表示正常语速，不传时使用默认语速。
`voice`	string	否	可以省略；仅接受空值或兼容占位值 `alloy`。指定音色请使用 `references[].speaker`。

当前不支持 audio_config.sample_rate、pitch_rate、speech_rate、loudness_rate、enable_subtitle 以及 watermark，请勿依赖这些字段生效。调速使用顶层 speed。instructions、metadata、ref_audio 也不属于当前接口支持的调用参数。

请省略 stream 和 stream_format。添加 stream: true 不会启用流式；stream_format: "sse" 会被拒绝。

输出格式

format	保存后扩展名	采样率	使用说明
`wav`	`.wav`	24000 Hz	带文件头，适合直接保存、播放和后处理。
`mp3`	`.mp3`	24000 Hz	适合常见播放器。
`pcm`	`.pcm`	24000 Hz	裸音频数据；播放端需要正确的采样格式、位深和声道信息，不能按 WAV 文件解码。
`ogg_opus`	`.ogg`	48000 Hz	Ogg 容器中的 Opus 音频，播放端需支持该格式。

输出音频文件的扩展名与请求格式对应。

参考资源与生成模式

平台根据 references 判断生成模式，不需要传额外的模式字段。若管理员为三种模式分别定价，按本次实际模式选价。

references 内容	生成模式
不传或 `[]`	纯文本生成
`audio_url`、`audio_data` 或 `speaker`	参考音频生成
`image_url` 或 `image_data`	参考图片生成

每个数组元素必须且只能包含以下一个非空字段：

字段	类型	说明
`audio_url`	string	可通过公网访问的 HTTP(S) 音频地址。
`audio_data`	string	音频文件的标准 Base64 编码，不带 `data:audio/...;base64,` 前缀。
`speaker`	string	已有且有权使用的音色 ID，不是任意名称或 `alloy`。
`image_url`	string	可通过公网访问的 HTTP(S) 图片地址。
`image_data`	string	图片文件的标准 Base64 编码，不带 data URL 前缀。

参考资源规则：

音频和图片不能混用，包括放在不同数组元素中也不可以。

音频参考最多 3 条，单条时长不超过 30 秒，单条文件不超过 10 MiB；格式为 WAV、MP3、PCM 或 Ogg Opus。当前平台将 speaker 元素也计入最多 3 个音频类参考的限制。

图片参考最多 1 张，文件不超过 10 MiB，支持 JPEG、PNG、WebP。

@音频1、@音频2 等编号应与提交的参考音频顺序对应。平台保持数组顺序，不替调用方重排或修正编号。

URL 不得包含用户名和密码。不要使用 localhost、内网地址或已经过期的签名地址。

Base64 和 URL 方式提交的参考文件均须满足上述格式、大小和时长要求。

纯文本生成

{
  "model": "seed-audio-1.0",
  "text_prompt": "用温柔自然的声音说：欢迎使用语音生成服务。",
  "audio_config": { "format": "mp3" }
}

参考音频生成

将示例中的参考地址替换为可通过公网访问的真实音频地址。

{
  "model": "seed-audio-1.0",
  "text_prompt": "参考@音频1的声音特点，说：你好，欢迎使用语音服务。",
  "references": [
    { "audio_url": "https://files.example.com/reference.mp3" }
  ],
  "audio_config": { "format": "wav" }
}

使用 Base64 时，将上述元素换为 {"audio_data":"<音频文件的标准 Base64>"}。只通过音色 ID 指定音色时，可换为 {"speaker":"<有效音色 ID>"}。

如果配置了参考音频输入时长收费，当前 URL 或裸 PCM 方式无法提供平台可确认的输入时长，会在调用前被拒绝。此时请传可解析的 Base64 WAV、MP3 或 Ogg Opus；仅收输出时长费用、输入时长单价为 0 时可以使用 URL。

参考图片生成

{
  "model": "seed-audio-1.0",
  "text_prompt": "你好，欢迎来到今天的故事时间。",
  "references": [
    { "image_url": "https://files.example.com/reference.png" }
  ],
  "audio_config": { "format": "wav" }
}

图片模式中的 text_prompt 填待合成的文本内容。使用 Base64 时，将元素换为 {"image_data":"<图片文件的标准 Base64>"}。

响应结构

成功返回 HTTP 200。以下时长和地址仅作结构示例：

{
  "id": "202610120216001668199008268d9d6example",
  "model": "seed-audio-1.0",
  "created": 1791785803,
  "data": {
    "audio": "<标准 Base64 音频数据>",
    "duration": 3.9,
    "original_duration": 3.9,
    "url": "https://token.kelly.cloud/api/audio/files/01234567-89ab-4cde-8f01-23456789abcd.wav"
  }
}

字段	类型	含义
`id`	string	平台请求 ID，与响应头 `X-Request-Id` 对应，可用于排查调用。
`model`	string	客户端请求的模型名称；使用平台模型别名时返回该别名。
`created`	integer	平台接收本次请求的创建时间，Unix 时间戳，单位秒，不是毫秒或音频生成耗时。
`data.audio`	string	原始音频的标准 Base64，可直接解码为文件。
`data.duration`	number 或 null	音频播放时长，单位秒；缺失或无效时为 null。
`data.original_duration`	number 或 null	原始生成时长，单位秒；输出时长计费使用此字段。
`data.url`	string	音频访问地址，可能具有有效期；无可用地址时可能为空字符串，此时仍可使用 Base64。

调速后 duration 与 original_duration 可能不同。不要用播放时长替代原始时长来核对输出时长账单。响应不包含 usage 字段，费用和用量明细在平台消费日志中查看。

成功响应不再包含 success、message。请根据 HTTP 状态和返回内容判断结果；失败响应仍使用 error 对象。X-Request-Id 是平台请求标识，与成功响应的 id 对应，排查时请一并提供。

音频地址与保存

拿到结果后，可以立即下载 data.url，也可以将 data.audio 解码后自行保存。访问地址可能过期，请勿将其当作永久地址；需要长期使用时，请保存音频文件。

下载响应中的音频地址无需附加平台 API 令牌。音频地址应按分享链接保管，避免泄露。即使 data.url 为空，仍可通过 data.audio 解码保存文件。

Python 调用并保存文件

以下示例仅使用 Python 3 标准库。设置 PLATFORM_API_KEY，可选设置 PLATFORM_BASE_URL（不含 /v1），然后执行。

示例的 180 秒是客户端等待超时，可根据业务调整，不代表平台承诺的生成时间。此示例没有自动重试。若请求超时或连接断开，生成可能已经完成并计费，应先凭请求记录核对状态，避免重复提交导致重复生成和扣费。

错误处理

失败响应使用 error 对象，与成功响应的 id/model/created/data 结构不同。以下示例仅列出调用方需要处理的字段：

{
  "error": {
    "message": "错误说明，可能附带 request id",
    "code": "insufficient_user_quota"
  }
}

错误码和状态码随错误原因变化，请结合 HTTP 状态、error.code 与 error.message 处理。

常见状态或消息	原因与处理
401 / Invalid token	检查平台令牌是否有效、是否传入正确平台。
403 / insufficient_user_quota	钱包或订阅额度不足，或不足以满足预扣要求。此时尚未调用生成接口。
reference 1 must contain exactly one resource or speaker	一个参考元素填了多个资源字段，或没有非空资源字段；每个元素只保留一项。
image and audio references cannot be mixed	同一请求混用了音频/音色与图片参考。
input and text_prompt must match when both are provided	两个文本字段冲突，保留一个或改为相同内容。
audio_config.format and response_format must match	两个格式字段冲突，建议只保留 `audio_config.format`。
提示不支持 SSE	去掉 `stream_format: "sse"`，使用同步 JSON 请求。
input duration pricing requires measurable reference audio	输入时长收费但参考音频时长不可确认，改传可解析 Base64，或联系管理员调整输入计费项。
text_prompt is required	确认请求带有非空的 `text_prompt` 或 `input`；仍报错时请提供平台请求 ID 联系技术支持。
502 / bad_response_body	音频结果无效或不完整等，提供平台请求 ID 联系技术支持。
503 / system_memory_overloaded	平台内存保护触发，联系管理员排查资源使用情况。

Seed-audio-1.0 语音生成对接文档

seed-audio-1.0 语音生成对接文档#

接入准备#

最小请求#

请求参数#

输出格式#

参考资源与生成模式#

纯文本生成#

参考音频生成#

参考图片生成#

响应结构#

音频地址与保存#

Python 调用并保存文件#

错误处理#