CosyVoice-3 语音合成 API接口文档

前言

CosyVoice 3.0 是一款具备零样本声音克隆能力的多语言 TTS 模型。它不仅支持中英日韩及多种中文方言的流式极速合成，更能仅通过少量参考音频精准复刻说话人音色。通过精细的参数控制（Instruct/Speed/Seed），您可以轻松驾驭语气、情绪与语速，实现高自然度与高一致性的语音生成。

概述

接口基础地址：https://www.yuntts.com/api/v1

认证方式：所有请求需要在 Header 中携带 Authorization: Bearer YOUR_API_KEY

1. CosyVoice-3 语音合成接口

提交 CosyVoice-3 语音合成异步任务。

接口地址

POST https://www.yuntts.com/api/v1/cosyyoice3_speech_generate

请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN  // API Key

请求参数（JSON）

注意：prompt_wav_url 和 prompt_wav_file 二选一必填。

提示：推荐使用 prompt_wav_url 方式（JSON 格式），无需上传文件。

请求示例

curl -X POST 'https://www.yuntts.com/api/v1/cosyyoice3_speech_generate' 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer YOUR_API_TOKEN' 
  -d '{
    "inputs": "要合成的文本内容",
    "prompt_wav_url": "https://example.com/reference.wav",
    "prompt_text": "参考音频对应的文字内容",
    "instruct_text": "指导文本，控制语音风格",
    "speed": 1.0,
    "seed": 12345
  }'

const response = await fetch('https://www.yuntts.com/api/v1/cosyyoice3_speech_generate', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN'
    },
    body: JSON.stringify({
        inputs: '要合成的文本内容',
        prompt_wav_url: 'https://example.com/reference.wav',
        speed: 1.0
    })
});

const data = await response.json();
console.log(data);

成功响应

{
    "code": 200,
    "status": "success",
    "message": "任务提交成功",
    "data": {
        "task_id": "abc123xyz",
        "char_count": 25,
        "cost": 0.01,
        "balance": 99.99,
        "status": "pending",
        "message": "语音合成任务已提交"
    }
}

响应字段说明

错误响应

{
    "code": 400,
    "status": "error",
    "error": "missing_prompt_audio",
    "message": "请提供音色参考音频（文件或URL）"
}

2. 任务状态查询接口

查询异步语音合成任务的状态和结果。

接口地址

POST https://www.yuntts.com/api/v1/speech_task_status

请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN  // API Key

请求参数（JSON）

请求示例

curl -X POST 'https://www.yuntts.com/api/v1/speech_task_status' 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer YOUR_API_TOKEN' 
  -d '{"task_id":"abc123xyz"}'

const response = await fetch('https://www.yuntts.com/api/v1/speech_task_status', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN'
    },
    body: JSON.stringify({ task_id: 'abc123xyz' })
});

const data = await response.json();
console.log(data);

成功响应（任务完成）

{
    "code": 200,
    "status": "success",
    "message": "获取状态成功",
    "data": {
        "task_id": "abc123xyz",
        "status": "completed",
        "progress": 100,
        "message": "语音合成成功",
        "audio_url": "https://oss.example.com/audio/abc123xyz.mp3"
    }
}

成功响应（任务进行中）

{
    "code": 200,
    "status": "success",
    "message": "获取状态成功",
    "data": {
        "task_id": "abc123xyz",
        "status": "in_progress",
        "progress": 45,
        "message": "任务正在处理中",
        "audio_url": ""
    }
}

响应字段说明

错误响应

{
    "code": 400,
    "status": "error",
    "error": "missing_task_id",
    "message": "缺少任务ID"
}

3. 任务取消接口

取消正在处理中的异步语音合成任务。

接口地址

POST https://www.yuntts.com/api/v1/speech_task_cancel

请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN  // API Key

请求参数（JSON）

请求示例

curl -X POST 'https://www.yuntts.com/api/v1/speech_task_cancel' 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer YOUR_API_TOKEN' 
  -d '{"task_id":"abc123xyz"}'

const response = await fetch('https://www.yuntts.com/api/v1/speech_task_cancel', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN'
    },
    body: JSON.stringify({ task_id: 'abc123xyz' })
});

const data = await response.json();
console.log(data);

成功响应

{
    "code": 200,
    "status": "success",
    "message": "取消成功",
    "data": {
        "task_id": "abc123xyz",
        "status": "cancelled",
        "message": "任务已取消，费用已返还"
    }
}

响应字段说明

错误响应

{
    "code": 400,
    "status": "error",
    "error": "task_completed",
    "message": "任务已完成，无法取消"
}

4. 通用响应格式

成功响应

{
    "code": 200,
    "status": "success",
    "message": "操作成功",
    "data": {
        // 业务数据
    }
}

错误响应

{
    "code": 400,
    "status": "error",
    "error": "error_code",
    "message": "错误描述信息"
}

响应字段说明

5. 错误码说明

6. 状态码说明

任务状态说明（用于 /speech_task_status 接口）：

前端状态展示建议

function getStatusDisplay(status) {
    const statusMap = {
        'pending': { text: '等待中', class: 'bg-secondary' },
        'in_progress': { text: '处理中', class: 'bg-warning' },
        'completed': { text: '已完成', class: 'bg-success' },
        'failed': { text: '失败', class: 'bg-danger' },
        'cancelled': { text: '已取消', class: 'bg-info' },
        'refunded': { text: '已退款', class: 'bg-secondary' }
    };
    return statusMap[status] || { text: status, class: 'bg-secondary' };
}

7. 使用流程

调用流程图

1. 提交任务
   │
   └─> POST /cosyyoice3_speech_generate
       返回: task_id
       │
       ▼
2. 轮询状态（建议 5秒/次）
   │
   └─> POST /speech_task_status
       │
       ├─ status = 'completed' ──> 获取 audio_url，完成
       │
       ├─ status = 'in_progress' ──> 继续轮询
       │
       └─ status = 'failed/cancelled' ──> 任务结束
              │
              ▼
3. 可选：取消任务
   │
   └─> POST /speech_task_cancel
       返回: 费用返还

轮询策略

// 推荐轮询逻辑
const pollInterval = 5000; // 5秒
const maxAttempts = 120;   // 最多轮询10分钟

for (let i = 0; i < maxAttempts; i++) {
    const result = await checkStatus(task_id);

    if (result.status === 'completed') {
        console.log('完成，音频地址:', result.audio_url);
        break;
    }

    if (result.status === 'failed') {
        console.log('失败:', result.message);
        break;
    }

    await sleep(pollInterval);
}

async function pollTaskStatus(taskId, apiKey) {
    const API_BASE = 'https://www.yuntts.com/api/v1';

    while (true) {
        const response = await fetch(API_BASE + '/speech_task_status', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Bearer ' + apiKey
            },
            body: JSON.stringify({ task_id: taskId })
        });

        const data = await response.json();

        if (data.code === 200 && data.data) {
            console.log('状态:', data.data.status);
            console.log('进度:', data.data.progress + '%');
            console.log('消息:', data.data.message);

            if (data.data.status === 'completed') {
                console.log('音频地址:', data.data.audio_url);
                break;
            }

            if (data.data.status === 'failed' || data.data.status === 'cancelled') {
                console.log('任务结束:', data.data.message);
                break;
            }
        }

        // 等待 5 秒后继续查询
        await new Promise(resolve => setTimeout(resolve, 5000));
    }
}

8. 定价说明

示例：合成 100 字文本，普通用户需 0.03 元，VIP 用户需 0.027 元，SVIP 用户需 0.024 元。

9. 注意事项

1. API 密钥：请妥善保管您的 API 密钥，不要在客户端代码中硬编码
2. 任务轮询：任务提交后请定期查询状态（建议 5 秒/次），直到任务完成或失败
3. 音频下载：返回的 audio_url 为 OSS 地址，有效期请咨询管理员
4. 退款政策：任务失败或取消时，费用会自动退还到用户账户
5. 文件上传：音频文件建议 5-30 秒，大小不超过 10MB
6. 字符限制：单次合成文本最大 600 字符

10. 常见问题

Q: 任务提交后多久能完成？

A: 完成时间取决于音频长度和服务器负载，通常 10-60 秒内完成。

Q: 如何复现相同的合成结果？

A: 设置相同的 seed 值即可复现相同结果。

Q: 任务失败会退款吗？

A: 是的，任务自动失败或手动取消都会自动退款。

Q: 可以同时提交多个任务吗？

A: 可以，支持并行提交多个任务。

Q: audio_url 的有效期是多久？

A: 具体有效期请咨询管理员，建议及时下载音频文件。

文档版本：1.0.0
最后更新：2024年1月
接口前缀：https://www.yuntts.com/api/v1