# vibevoice_service **Repository Path**: xiaobo0903/vibevoice_service ## Basic Information - **Project Name**: vibevoice_service - **Description**: 基于vibevoice做的接口的服务。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-28 - **Last Updated**: 2026-06-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # VibeVoice API 接口文档 基于 VibeVoice 模型的语音克隆生成服务 API。 ## 服务概述 VibeVoice API 提供文本转语音的克隆生成功能,支持使用自定义声音样本进行语音合成。 **基础URL**: `http://localhost:8000` --- ## 目录 - [获取可用声音素材](#1-获取可用声音素材) - [获取指定声音素材](#2-获取指定声音素材) - [更新声音素材配置](#3-更新声音素材配置) - [提交语音生成任务](#4-提交语音生成任务) - [查询任务状态](#5-查询任务状态) - [列出所有任务](#6-列出所有任务) - [健康检查](#7-健康检查) --- ## 数据模型 ### VoiceInfo 声音素材信息 | 字段 | 类型 | 描述 | |------|------|------| | voice_id | string | 声音素材ID(如 man1, woman2) | | name | string | 显示名称(如 男声 1, 女声 2) | | gender | string | 性别(male/female/unknown) | | path | string | 声音样本文件完整路径 | | speed | float | 语速,1.0 为正常速度 | ### TaskSubmitRequest 任务提交请求 | 字段 | 类型 | 必填 | 描述 | |------|------|------|------| | content | string | 是 | 需要生成的文本内容 | | voice_id | string | 是 | 声音ID(如 man1, woman2) | | name | string | 是 | 声音显示名称(如 男声 1, 女声 2) | | gender | string | 是 | 性别(male/female) | | path | string | 是 | 声音样本完整路径 | | speed | float | 否 | 语速,1.0 为正常速度(默认 1.0) | | cfg_scale | float | 否 | CFG 规模参数(默认 1.3) | | disable_prefill | bool | 否 | 是否禁用语音克隆(默认 false) | ### TaskQueryResponse 任务查询响应 | 字段 | 类型 | 描述 | |------|------|------| | task_id | string | 任务ID | | status | string | 任务状态(pending/running/completed/failed) | | progress | float | 进度(0.0 ~ 1.0) | | created_at | float | 任务创建时间戳 | | started_at | float | 任务开始时间戳(可选) | | completed_at | float | 任务完成时间戳(可选) | | error | string | 错误信息(可选) | | result | object | 任务结果(可选,成功时包含以下字段) | ### TaskResult 任务结果 | 字段 | 类型 | 描述 | |------|------|------| | audio_url | string | 音频文件访问URL | | audio_path | string | 音频文件完整路径 | | duration | float | 音频时长(秒) | | generation_time | float | 生成耗时(秒) | | content | string | 原始文本内容 | | voice_id | string | 使用的声音ID | | name | string | 使用的声音名称 | | gender | string | 性别 | | path | string | 使用的声音样本路径 | | speed | float | 语速参数 | | stext | string | ASR 识别的文本内容 | | timestamps | array | 文字时间戳列表 | ### VoiceUpdateRequest 声音配置更新请求 | 字段 | 类型 | 必填 | 描述 | |------|------|------|------| | voice_id | string | 是 | 声音ID(如 man1, woman2) | | name | string | 是 | 声音显示名称(如 男声 1, 女声 2) | | gender | string | 是 | 性别(male/female) | | path | string | 是 | 声音样本完整路径 | | speed | float | 否 | 语速,1.0 为正常速度(默认 1.0) | ### VoiceUpdateResponse 声音配置更新响应 | 字段 | 类型 | 描述 | |------|------|------| | voice_id | string | 声音ID | | name | string | 声音显示名称 | | gender | string | 性别 | | path | string | 声音样本完整路径 | | speed | float | 语速 | | message | string | 操作结果消息 | --- ## 接口详情 ### 1. 获取可用声音素材 获取所有可用的克隆声音素材列表。 **请求** ``` GET /api/voices ``` **响应示例** ```json { "voices": [ { "voice_id": "man1", "name": "男声 1", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man1/sample.wav", "speed": 1.0 }, { "voice_id": "man2", "name": "男声 2", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man2/sample.wav", "speed": 1.0 }, { "voice_id": "woman1", "name": "女声 1", "gender": "female", "path": "/home/aigc/pserver/ttsvoice/woman1/sample.wav", "speed": 1.0 } ] } ``` --- ### 2. 获取指定声音素材 根据声音ID获取特定声音素材的详细信息。 **请求** ``` GET /api/voices/{voice_id} ``` **参数** | 参数 | 类型 | 描述 | |------|------|------| | voice_id | string | 声音素材ID(如 man1, woman2) | **响应示例** ```json { "voice_id": "man1", "name": "男声 1", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man1/sample.wav", "speed": 1.0 } ``` **错误响应** ```json { "detail": "声音素材不存在" } ``` --- ### 3. 更新声音素材配置 更新指定声音素材的配置信息(voice_id、name、gender、path、speed)。 **请求** ``` PUT /api/voices/{voice_id} Content-Type: application/json ``` **参数** | 参数 | 类型 | 描述 | |------|------|------| | voice_id | string | 要更新的声音ID(URL参数) | **请求示例** ```json { "voice_id": "man2", "name": "男声 2", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man2/sample.wav", "speed": 1.2 } ``` **响应示例** ```json { "voice_id": "man2", "name": "男声 2", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man2/sample.wav", "speed": 1.2, "message": "声音配置更新成功" } ``` **错误响应** ```json { "detail": "声音素材不存在" } ``` 或 ```json { "detail": "声音样本文件不存在: /path/to/file.wav" } ``` --- ### 4. 提交语音生成任务 提交一个新的语音生成任务。 **请求** ``` POST /api/tasks Content-Type: application/json ``` **请求示例** ```json { "content": "你好,欢迎使用语音合成服务。", "voice_id": "man1", "name": "男声 1", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man1/sample.wav", "speed": 1.0, "cfg_scale": 1.3, "disable_prefill": false } ``` **响应示例** ```json { "task_id": "a1b2c3d4", "message": "任务已提交,请在 30 秒后查询任务进度" } ``` --- ### 5. 查询任务状态 查询指定任务的状态和结果。 **请求** ``` GET /api/tasks/{task_id} ``` **参数** | 参数 | 类型 | 描述 | |------|------|------| | task_id | string | 任务ID(如 a1b2c3d4) | **响应示例(进行中)** ```json { "task_id": "a1b2c3d4", "status": "running", "progress": 0.5, "created_at": 1706236800.123, "started_at": 1706236800.456, "completed_at": null, "error": null, "result": null } ``` **响应示例(已完成)** ```json { "task_id": "a1b2c3d4", "status": "completed", "progress": 1.0, "created_at": 1706236800.123, "started_at": 1706236800.456, "completed_at": 1706236815.789, "error": null, "result": { "audio_url": "/outputs/a1b2c3d4.wav", "audio_path": "/home/aigc/pserver/vibevoice_service/outputs/a1b2c3d4.wav", "duration": 3.5, "generation_time": 12.34, "content": "你好,欢迎使用语音合成服务。", "voice_id": "man1", "name": "男声 1", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man1/sample.wav", "speed": 1.0, "stext": "你好,欢迎使用语音合成服务。", "timestamps": [ { "word": "你好", "start": 0.0, "end": 0.5 }, { "word": "欢迎使用", "start": 0.6, "end": 1.2 } ] } } ``` **错误响应** ```json { "detail": "任务不存在" } ``` --- ### 6. 列出所有任务 列出所有任务(按创建时间倒序)。 **请求** ``` GET /api/tasks?limit=100 ``` **参数** | 参数 | 类型 | 默认值 | 描述 | |------|------|--------|------| | limit | int | 100 | 返回的最大任务数量 | **响应示例** ```json [ { "task_id": "a1b2c3d4", "status": "completed", "progress": 1.0, "created_at": 1706236800.123, "started_at": 1706236800.456, "completed_at": 1706236815.789, "error": null, "result": {...} }, { "task_id": "e5f6g7h8", "status": "pending", "progress": 0.0, "created_at": 1706236795.111, "started_at": null, "completed_at": null, "error": null, "result": null } ] ``` --- ### 7. 健康检查 检查服务健康状态和GPU可用性。 **请求** ``` GET /health ``` **响应示例** ```json { "status": "healthy", "gpu_available": true, "gpu_device": "NVIDIA Tesla T4" } ``` --- ### 8. 服务首页 获取API服务的基本信息。 **请求** ``` GET / ``` **响应示例** ```json { "service": "VibeVoice API", "version": "1.0.0", "description": "文生音频模型服务", "endpoints": { "POST /api/tasks": "提交语音生成任务", "GET /api/tasks/{task_id}": "查询任务状态", "GET /api/tasks": "列出所有任务", "GET /api/voices": "获取可用声音素材", "GET /api/voices/{voice_id}": "获取指定声音素材", "PUT /api/voices/{voice_id}": "更新声音素材配置" } } ``` --- ## 错误代码 | HTTP状态码 | 描述 | |-----------|------| | 200 | 请求成功 | | 400 | 请求参数错误(如声音样本文件不存在) | | 404 | 资源不存在(如任务ID、声音素材ID) | | 500 | 服务器内部错误 | --- ## 使用示例 ### Python 请求示例 ```python import requests # 1. 获取可用声音 voices_response = requests.get("http://localhost:8000/api/voices") voices = voices_response.json()["voices"] print(f"可用声音: {len(voices)} 个") for voice in voices: print(f" - {voice['voice_id']}: {voice['name']}") # 2. 选择一个声音并提交生成任务 voice = voices[0] # 选择第一个声音 task_request = { "content": "今天天气真不错!", "voice_id": voice["voice_id"], "name": voice["name"], "gender": voice["gender"], "path": voice["path"], "speed": 1.0 } task_response = requests.post("http://localhost:8000/api/tasks", json=task_request) task_data = task_response.json() task_id = task_data["task_id"] print(f"任务已提交,ID: {task_id}") # 3. 轮询查询任务状态 import time while True: status_response = requests.get(f"http://localhost:8000/api/tasks/{task_id}") status_data = status_response.json() print(f"状态: {status_data['status']}, 进度: {status_data['progress']:.0%}") if status_data["status"] in ["completed", "failed"]: if status_data["status"] == "completed": result = status_data["result"] print(f"生成完成!") print(f"音频URL: {result['audio_url']}") print(f"音频时长: {result['duration']:.2f}秒") else: print(f"任务失败: {status_data['error']}") break time.sleep(2) # 4. 更新声音配置(可选) update_request = { "voice_id": "custom_voice", "name": "自定义声音", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man1/sample.wav", "speed": 1.2 } update_response = requests.put("http://localhost:8000/api/voices/man1", json=update_request) print(f"配置更新结果: {update_response.json()}") ``` ### cURL 请求示例 ```bash # 获取声音列表 curl http://localhost:8000/api/voices # 获取指定声音 curl http://localhost:8000/api/voices/man1 # 更新声音配置 curl -X PUT http://localhost:8000/api/voices/man1 \ -H "Content-Type: application/json" \ -d '{"voice_id": "custom_voice", "name": "自定义声音", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man1/sample.wav", "speed": 1.2}' # 提交任务 curl -X POST http://localhost:8000/api/tasks \ -H "Content-Type: application/json" \ -d '{"content": "你好", "voice_id": "man1", "name": "男声 1", "gender": "male", "path": "/home/aigc/pserver/ttsvoice/man1/sample.wav", "speed": 1.0}' # 查询任务 curl http://localhost:8000/api/tasks/{task_id} ``` --- ## 声音素材列表 基于 `voices.json` 配置的声音素材: | ID | 名称 | 性别 | 路径 | |----|------|------|------| | man1 | 男声 1 | male | ttsvoice/man1/sample.wav | | man2 | 男声 2 | male | ttsvoice/man2/sample.wav | | man3 | 男声 3 | male | ttsvoice/man3/sample.wav | | man4 | 男声 4 | male | ttsvoice/man4/sample.wav | | man5 | 男声 5 | male | ttsvoice/man5/sample.wav | | woman1 | 女声 1 | female | ttsvoice/woman1/sample.wav | | woman2 | 女声 2 | female | ttsvoice/woman2/sample.wav | | woman3 | 女声 3 | female | ttsvoice/woman3/sample.wav | | woman4 | 女声 4 | female | ttsvoice/woman4/sample.wav | | woman5 | 女声 5 | female | ttsvoice/woman5/sample.wav |