F5-TTS-语音合成异步接口API文档

前言

F5-TTS 异步语音合成接口分为两个步骤：

1. 提交任务 - 提交合成请求，立即返回 request_id
2. 查询结果 - 使用 request_id 轮询查询任务状态，完成后返回音频 URL

特点：

• 适合较长文本（≤2000字符）
• 提交即返回，不阻塞调用方
• 音频自动下载到本站服务器，永久有效
• 通过 request_id 轮询查询任务进度

一、提交任务

接口地址： POST https://www.yuntts.com/api/v1/f5-tts-async

请求 Headers

请求 Body

请求示例

curl --location --request POST 'https://www.yuntts.com/api/v1/f5-tts-async' 
--header 'Authorization: Bearer sk-your-api-key' 
--header 'Content-Type: application/json' 
--data-raw '{
    "gen_text": "这是一段较长的测试文本，适用于异步合成模式，提交后可以立即获取任务ID，稍后再来查询合成结果。",
    "ref_audio_url": "https://example.com/ref-speaker.wav",
    "ref_text": "这是参考音频说的内容"
}'

响应

成功响应（200）

{
    "code": 200,
    "message": "任务提交成功",
    "data": {
        "request_id": "019e4446-94d6-7763-a19e-735c2c1be9c5",
        "char_count": 46,
        "cost": 0.01,
        "status": "pending",
        "queue_position": 0,
        "message": "任务提交成功"
    }
}

错误响应

{
    "code": 400,
    "error": "empty_text",
    "message": "请输入要合成的文字"
}

二、查询结果

接口地址： POST https://www.yuntts.com/api/v1/f5-tts-status

请求 Headers

请求 Body

请求示例

curl --location --request POST 'https://www.yuntts.com/api/v1/f5-tts-status' 
--header 'Authorization: Bearer sk-your-api-key' 
--header 'Content-Type: application/json' 
--data-raw '{
    "request_id": "019e4446-94d6-7763-a19e-735c2c1be9c5"
}'

响应

处理中响应（200）

{
    "code": 200,
    "message": "任务正在处理中",
    "data": {
        "task_id": "019e4446-94d6-7763-a19e-735c2c1be9c5",
        "status": "processing",
        "message": "任务正在处理中"
    }
}

完成响应（200）

{
    "code": 200,
    "message": "语音合成成功",
    "data": {
        "task_id": "019e4446-94d6-7763-a19e-735c2c1be9c5",
        "status": "completed",
        "char_count": 46,
        "cost": 0.01,
        "audio_url": "https://www.yuntts.com/wp-content/uploads/audio/processed/f5tts_async_xxx.wav",
        "file_size": 291644,
        "content_type": "application/octet-stream",
        "message": "语音合成成功"
    }
}

错误响应

{
    "code": 500,
    "error": "task_failed",
    "message": "任务处理失败"
}

调用流程

sequenceDiagram
    调用方->>+F5-TTS异步接口: POST /api/v1/f5-tts-async
    F5-TTS异步接口-->>-调用方: { request_id, status: "pending" }

    loop 轮询（建议间隔3-5秒）
        调用方->>+F5-TTS状态接口: POST /api/v1/f5-tts-status
        F5-TTS状态接口-->>-调用方: { status: "processing" }
    end

    调用方->>+F5-TTS状态接口: POST /api/v1/f5-tts-status
    F5-TTS状态接口-->>-调用方: { status: "completed", audio_url }

计费说明

• 价格： ¥400/百万字符
• 计费方式： 汉字按2倍计数，其他字符按1倍计数
• 最低收费： 0.001 元
• 免费额度：
  • BossVIP 用户：享有永久免费字符额度（后台配置）
  • VIP 用户：享有月度免费字符额度（后台配置）
  • 超出免费额度部分：BossVIP 8折、VIP 9折