openapi: 3.0.3 info: title: FishAudio 专属语音合成 version: 1.0.1 description: >- 将此文件导入扣子私有云端插件。工具会使用可直接下载的授权音频创建临时 私有音色，再异步合成目标文本；任务成功或失败后删除临时音色。每位用户在运行时通过 Authorization 参数 填写自己的 Fish Audio API Key。 servers: - url: https://fishaudio.org paths: /api/open/v1/speech/voice-clone-tts/jobs: post: operationId: create_personal_voice summary: 创建专属音色并合成文字 description: >- 创建一个临时私有音色，然后启动一个 TTS 任务；任务结束后删除该音色。保存 data.id。 只有重试完全相同的请求时才复用原 Idempotency-Key；新生成必须使用新值。 parameters: - name: Authorization in: header required: true description: 填写 Fish Audio API Key，格式为 Bearer + 空格 + API Key。 example: Bearer YOUR_FISH_AUDIO_API_KEY schema: type: string - name: Idempotency-Key in: header required: true description: >- 每次新生成填写一个唯一值。仅重试完全相同的请求时复用，避免重复创建和扣费。 example: coze-personal-voice-20260820-001 schema: type: string maxLength: 200 requestBody: required: true content: application/json: schema: type: object required: - source_audio_url - text properties: source_audio_url: type: string format: uri description: >- 客户自有或已获授权、Fish Audio 服务端可直接下载的参考音频 URL。 最大下载大小为 10 MB。 text: type: string minLength: 1 maxLength: 5000 description: 使用新创建的私有音色合成的目标文本，最长 5000 字符。 voice_name: type: string minLength: 1 maxLength: 100 description: 可选。临时私有音色的名称，最长 100 字符。 file_name: type: string minLength: 1 maxLength: 255 description: 可选。带音频扩展名的源文件名，最长 255 字符。 model_id: type: string default: fishaudio-s21pro-flash description: Fish Audio 语音合成模型，首次测试建议使用默认值。 enum: - fishaudio-s21pro - fishaudio-s21pro-flash - fishaudio-s2pro - fishaudio-s1 format: type: string default: mp3 description: 输出音频格式，默认为 mp3。 enum: - mp3 - wav speed: type: number minimum: 0.5 maximum: 2 default: 1 description: 语速倍率，范围 0.5～2，默认为 1。 volume: type: number minimum: -20 maximum: 20 default: 0 description: 输出音量调整，范围 -20～20，默认为 0。 stability: type: number minimum: 0.5 maximum: 1.5 description: 可选。控制声音稳定性，范围 0.5～1.5。 similarity: type: number minimum: 0.5 maximum: 1.5 description: 可选。控制音色相似度，范围 0.5～1.5。 language: type: string maxLength: 32 description: 可选。指定合成语言提示，需所选模型支持。 instruction: type: string maxLength: 1600 description: 可选。描述角色、方言、语气、节奏或情绪，最长 1600 字符。 text_normalization: type: boolean default: true description: 合成前规范化文本。除非需要保留特殊格式，否则保持为 true。 responses: '200': description: 扣子兼容的成功响应结构；线上 API 实际使用 HTTP 202 接受任务。 content: application/json: schema: type: object properties: success: type: boolean description: API 请求是否已成功接受。 message: type: string description: 便于阅读的 API 响应信息。 requestId: type: string description: 用于故障排查的请求标识。 data: type: object description: 已创建音色和异步合成任务的详情。 properties: id: type: string description: 保存该值，后续作为 jobId 查询任务。 status: type: string description: 当前任务状态。 enum: - pending - processing - completed - failed stage: type: string description: 当前处理阶段。 progress: type: number description: 处理进度，范围 0～100。 voice_id: type: string description: 使用授权音频创建的临时私有音色 ID。 voice_name: type: string description: 临时私有音色的名称。 audio_url: type: string format: uri description: 合成完成后的临时播放 URL。 download_url: type: string format: uri description: 合成完成后的临时下载 URL。 expires_at: type: string description: 临时音频 URL 的过期时间。 error_code: type: string description: 任务失败时的错误码。 error_message: type: string description: 任务失败时的错误详情。 quota_remaining: type: number description: 请求完成后 Fish Audio 账户的剩余额度。 created_at: type: string description: 任务创建时间。 updated_at: type: string description: 任务最近更新时间。 completed_at: type: string description: 任务完成时间（如有）。 '202': description: 音色已创建，线上 API 已接受 TTS 任务。 content: application/json: schema: type: object properties: success: type: boolean description: API 请求是否已成功接受。 requestId: type: string description: 用于故障排查的请求标识。 data: type: object description: 已接受的异步合成任务详情。 properties: id: type: string description: 保存该值，后续作为 jobId 查询任务。 status: type: string description: 当前任务状态。 voice_id: type: string description: 使用授权音频创建的临时私有音色 ID。 /api/open/v1/speech/voice-clone-tts/jobs/{jobId}: get: operationId: get_personal_voice_job summary: 查询专属音色合成任务 description: >- 使用原任务 ID 查询进度。查询不会创建另一个音色，也不会重复扣费。 parameters: - name: Authorization in: header required: true description: 填写 Fish Audio API Key，格式为 Bearer + 空格 + API Key。 example: Bearer YOUR_FISH_AUDIO_API_KEY schema: type: string - name: jobId in: path required: true description: 填写 create_personal_voice 返回的 data.id。 schema: type: string responses: '200': description: 任务状态查询成功。 content: application/json: schema: type: object properties: success: type: boolean description: 查询是否成功完成。 message: type: string description: 便于阅读的 API 响应信息。 requestId: type: string description: 用于故障排查的请求标识。 data: type: object description: 当前私有音色合成任务的详情。 properties: id: type: string description: 原始任务 ID。 status: type: string description: 当前任务状态。 enum: - pending - processing - completed - failed stage: type: string description: 当前处理阶段。 progress: type: number description: 处理进度，范围 0～100。 voice_id: type: string description: 使用授权音频创建的临时私有音色 ID。 voice_name: type: string description: 临时私有音色的名称。 audio_url: type: string format: uri description: 合成完成后的临时播放 URL。 download_url: type: string format: uri description: 合成完成后的临时下载 URL。 expires_at: type: string description: 临时音频 URL 的过期时间。 error_code: type: string description: 任务失败时的错误码。 error_message: type: string description: 任务失败时的错误详情。 quota_remaining: type: number description: 请求完成后 Fish Audio 账户的剩余额度。 created_at: type: string description: 任务创建时间。 updated_at: type: string description: 任务最近更新时间。 completed_at: type: string description: 任务完成时间（如有）。