AI Artist API 驱动的声音克隆与语音合成工具。

声音复刻技能，使用 AI Artist API 进行音色克隆和语音合成。支持查询已有音色、上传音频创建新音色、使用指定音色合成语音。 ⚠️ 使用前必须设置环境变量 AI_ARTIST_TOKEN 为你的 API Key！ 获取 API Key：访问 https://staging.kocgo.vip/index...

Security Scan

The skill's code and instructions generally match a voice-cloning tool, but there are inconsistent and unexpected details (undeclared required API key, a localhost file-upload endpoint, and an embedded example API key) that warrant caution before use.

Purpose & Capability

The skill is a voice-clone tool and the runtime code calls the stated AI Artist API (staging.kocgo.vip) and provides list/create/synthesize flows — this matches the name/description. However, the registry metadata lists no required environment variables while SKILL.md and scripts clearly require AI_ARTIST_TOKEN; that's an incoherence. Also the script uses a FILE_UPLOAD_URL pointing to http://localhost:8080/system/fileUpload/upload for uploading audio, which is unexpected for a remote API integration and is not explained as a prerequisite service in the top-level metadata.

Instruction Scope

SKILL.md only asks users to set AI_ARTIST_TOKEN and run the provided Python script (consistent). The script will read .env files in the script directory or skill root for the API key (explicit in code). It also will upload arbitrary local files (provided via --audio) to a file-upload endpoint and can download synthesized audio to ~/.openclaw/workspace/audio. No instructions ask for unrelated system data, but the implicit search for .env files and the automatic upload behavior should be noted.

Install Mechanism

There is no install spec (instruction-only with an included Python script). No external downloads or installers are executed by an installer. This is the lower-risk pattern for install mechanism.

Credentials

The skill requires an API key (AI_ARTIST_TOKEN) to call the external API — appropriate for this functionality — but the registry metadata did not declare this required env var or a primary credential, which is an inconsistency. Additionally, SKILL.md includes a concrete example API key value in the docs (sk-5c6c2627...), which is dangerous: users might paste it or assume it is valid, and it exposes a token-like string in the repo. The script sends the API key in the x-api-key header to both staging.kocgo.vip and to the file upload endpoint; the latter is an unencrypted http://localhost endpoint (not HTTPS) and would receive the key if the upload call includes headers — the code does include the x-api-key header for uploads.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It does not modify other skills or global config. It stores downloaded audio in a standard per-user path (~/.openclaw/workspace/audio). Autonomous invocation is allowed by default but is not combined with other high-privilege indicators.

What to consider before installing

This skill appears to implement the voice-cloning features it advertises, but there are a few red flags you should address before installing or running it: - Metadata mismatch: The registry metadata does not declare the required AI_ARTIST_TOKEN env var though SKILL.md and the script require it. Expect to set AI_ARTIST_TOKEN yourself; ensure the registry metadata is corrected if you need automated checks. - Local upload endpoint: The script POSTS local audio files to http://localhost:8080/system/fileUpload/upload. That means either you must run a local uploader service that forwards files to OSS, or uploads will fail. If you do run a local service, be sure you trust it, as it will receive any file you ask the script to upload and the API key in the header. - Example API key present: The documentation includes a sample token-like value. Do not assume it is valid or safe to use; never paste tokens from examples into real services. Treat any displayed token string as potentially sensitive and replace it with your own key. - Where your API key is sent: The key will be sent to the staging.kocgo.vip endpoints (over HTTPS) and to the localhost upload endpoint (over HTTP). If you don't control the local endpoint, that could leak your key. Confirm the intended upload host and change FILE_UPLOAD_URL in scripts/voice_clone.py to the correct HTTPS upload endpoint before use. - File access: The script will read any local file path you pass via --audio and may read .env files in the script directory and its parent. Review those files to avoid accidental leakage of other secrets. Recommendation: only run this skill in an environment you control (or sandbox), verify and if needed edit FILE_UPLOAD_URL to a trusted HTTPS endpoint, remove or update any example tokens in docs, and ensure the metadata correctly declares AI_ARTIST_TOKEN before granting the skill broader access.

Voice Clone - 声音复刻技能

使用 AI Artist API 进行音色克隆和语音合成的完整解决方案。基于 CosyVoice v3.5 Plus 模型，支持高质量的音色复刻和文本转语音。

🎯 技能概述

本技能提供三大核心功能：

功能	说明	典型场景
查询音色	列出系统中所有可用音色	查看已有音色库，选择合适的声音
音色克隆	上传音频创建新的音色	复刻自己的声音、领导的声音、明星声音等
语音合成	使用指定音色生成语音	用特定声音朗读文本、生成配音、制作语音消息

⚠️ 首次使用必读

1. 获取 API Key

访问 https://staging.kocgo.vip/index 注册并登录，然后在控制台创建你的 API Key。

2. 设置环境变量

在使用前，你必须先设置自己的 API Key：

# Windows PowerShell
$env:AI_ARTIST_TOKEN="sk-your_api_key_here"

# Linux/macOS/Git Bash (Windows)
export AI_ARTIST_TOKEN="sk-your_api_key_here"

3. 验证配置

python scripts/voice_clone.py --list

如果看到音色列表，说明配置成功！

🚀 快速开始

基础用法

# 1. 列出所有可用音色
python scripts/voice_clone.py --list

# 2. 使用音色 ID 合成语音
python scripts/voice_clone.py --synthesize --id 10 --text "大家好，我是测试语音"

# 3. 使用音色名称合成语音
python scripts/voice_clone.py --synthesize --name "蔡总的音色" --text "你好世界"

# 4. 下载合成的音频到本地
python scripts/voice_clone.py --synthesize --id 10 --text "你好" --download

创建新音色

# 使用本地音频文件创建音色
python scripts/voice_clone.py --create --name "我的音色" --audio "./my_voice.mp3"

# 使用在线音频 URL 创建音色
python scripts/voice_clone.py --create --name "我的音色" --audio-url "https://example.com/voice.mp3"

# 指定音色前缀
python scripts/voice_clone.py --create --name "客服音色" --audio "./cs.mp3" --prefix "CustomerService"

📋 详细使用指南

一、查询可用音色

列出系统中所有音色及其状态：

python scripts/voice_clone.py --list

输出示例：

[INFO] 共有 4 个音色

可用音色列表:
  [13] 王俏的音色 [OK] - cosyvoice-v3.5-plus
  [12] 测试 11 [OK] - cosyvoice-v3.5-plus
  [10] 蔡总的音色 [OK] - cosyvoice-v3.5-plus
  [4] 测试音色 [OK] - cosyvoice-v3.5-plus

状态说明：

状态	说明	是否可用
OK	音色已就绪	✅ 可用
DEPLOYING	音色部署中	❌ 暂不可用
其他	音色异常	❌ 不可用

二、语音合成

方式 1：使用音色 ID

python scripts/voice_clone.py --synthesize --id 13 --text "真正重要的东西，用眼睛是看不见的，只有用心才能看清。"

方式 2：使用音色名称

python scripts/voice_clone.py --synthesize --name "王俏的音色" --text "你好，欢迎使用库阔 AI"

方式 3：合成并下载

# 下载到默认目录 (~/.openclaw/workspace/audio/)
python scripts/voice_clone.py --synthesize --id 13 --text "测试语音" --download

# 下载到指定目录
python scripts/voice_clone.py --synthesize --id 13 --text "测试语音" --download --output-dir "./my_audio"

三、创建新音色

从本地音频文件创建

# 支持 MP3、WAV 等常见格式
python scripts/voice_clone.py --create --name "我的声音" --audio "./my_voice.mp3"

# 使用完整路径
python scripts/voice_clone.py --create --name "领导音色" --audio "C:\Users\admin\Downloads\leader_voice.wav"

从在线 URL 创建

python scripts/voice_clone.py --create --name "网络音色" --audio-url "https://example.com/voice.mp3"

指定音色前缀

python scripts/voice_clone.py --create --name "客服小王" --audio "./wang.mp3" --prefix "CustomerService"

🎙️ 音色克隆最佳实践

音频素材要求

要求	说明
格式	MP3、WAV、M4A 等常见音频格式
时长	10-60 秒（推荐 30 秒左右）
音质	清晰的人声，无明显背景噪音
内容	纯人声朗读，无背景音乐
采样率	16kHz 或以上

录制建议

1. 环境安静 - 选择安静的房间，关闭空调、风扇等噪音源
2. 距离适中 - 麦克风距离嘴巴 10-15 厘米
3. 语速均匀 - 用正常语速朗读，不要过快或过慢
4. 情感自然 - 用自然的情感朗读，不要过于夸张
5. 内容多样 - 包含不同的音调、韵律，有助于模型学习

推荐的录音文本

你好，我是 XXX。这是一段用于音色克隆的录音样本。
我希望用我的声音来生成各种语音内容，包括问候语、通知、
故事朗读等。请确保录音清晰，语速适中，情感自然。
谢谢你的配合。

📊 参数说明

全局参数

参数	必填	说明
--list	三选一	列出所有可用音色
--synthesize	三选一	语音合成模式
--create	三选一	创建新音色模式

合成模式参数

参数	必填	说明	示例
--id	与 --name 二选一	音色 ID	--id 13
--name	与 --id 二选一	音色名称	--name "王俏的音色"
--text	✅	要合成的文本	--text "你好世界"
--download	否	下载音频到本地	--download
--output-dir	否	音频保存目录	--output-dir "./audio"

创建音色参数

参数	必填	说明	示例
--name	✅	音色名称	--name "我的音色"
--audio	与 --audio-url 二选一	本地音频路径	--audio "./voice.mp3"
--audio-url	与 --audio 二选一	在线音频 URL	--audio-url "https://..."
--prefix	否	音色前缀	--prefix "DeepSop"

🔧 环境配置

方式 1：临时设置（当前终端有效）

# Windows PowerShell
$env:AI_ARTIST_TOKEN="sk-5c6c262755dc43d59ec5a742a7e80202"

# Linux/macOS
export AI_ARTIST_TOKEN="sk-5c6c262755dc43d59ec5a742a7e80202"

方式 2：永久设置（推荐）

创建 .env 文件（在脚本同目录或技能根目录）：

AI_ARTIST_TOKEN=sk-your_api_key_here

方式 3：系统环境变量

Windows:

[System.Environment]::SetEnvironmentVariable('AI_ARTIST_TOKEN', 'sk-your_api_key_here', 'User')

Linux/macOS:

echo 'export AI_ARTIST_TOKEN="sk-your_api_key_here"' >> ~/.bashrc
source ~/.bashrc

💡 实用场景示例

场景 1：用特定音色发送语音消息

# 用蔡总的音色发送通知
python scripts/voice_clone.py --synthesize --name "蔡总的音色" \
  --text "各位同事，下午三点在会议室召开周会，请准时参加。" --download

场景 2：批量生成语音

# 生成多个语音片段
python scripts/voice_clone.py --synthesize --id 13 --text "第一章：开始" --download --output-dir "./audiobook/ch1"
python scripts/voice_clone.py --synthesize --id 13 --text "第二章：发展" --download --output-dir "./audiobook/ch2"
python scripts/voice_clone.py --synthesize --id 13 --text "第三章：高潮" --download --output-dir "./audiobook/ch3"

场景 3：创建多人音色库

# 为团队创建音色库
python scripts/voice_clone.py --create --name "客服小王" --audio "./wang.mp3"
python scripts/voice_clone.py --create --name "客服小李" --audio "./li.mp3"
python scripts/voice_clone.py --create --name "客服小张" --audio "./zhang.mp3"

# 查看音色列表
python scripts/voice_clone.py --list

场景 4：语音消息回复

# 收到语音后，用相同音色回复
# 1. 从语音消息提取音频
# 2. 创建音色（如果不存在）
python scripts/voice_clone.py --create --name "用户音色" --audio "./user_voice.wav"
# 3. 用该音色合成回复
python scripts/voice_clone.py --synthesize --name "用户音色" --text "收到，我会尽快处理。" --download

⚠️ 注意事项

必须遵守

1. API Key 安全

   • 不要将 API Key 提交到代码仓库
   • 使用 .env 文件时加入 .gitignore
   • 定期更换 API Key

2. 音色状态检查

   • 只有 status: "OK" 的音色可用于语音合成
   • DEPLOYING 状态的音色需要等待部署完成

3. 音频格式要求

   • 上传的音频建议为 MP3 或 WAV 格式
   • 时长 10-60 秒效果最佳
   • 确保音频清晰，无明显噪音

4. 文本长度限制

   • 合成文本建议控制在 500 字以内
   • 过长文本可能失败或效果不佳

性能优化

优化项	建议
音频素材	使用 30 秒左右的清晰录音
文本长度	单次合成不超过 200 字
并发请求	避免同时发起多个合成请求
错误处理	检查返回状态码，失败时重试

🔍 故障排查

问题 1：提示 "未配置 API_ARTIST_TOKEN"

原因： 环境变量未设置

解决：

# Windows PowerShell
$env:AI_ARTIST_TOKEN="sk-your_api_key_here"

# 或创建 .env 文件
echo "AI_ARTIST_TOKEN=sk-your_api_key_here" > .env

问题 2：音色状态为 DEPLOYING

原因： 音色正在部署中

解决： 等待几分钟后重新查询状态

python scripts/voice_clone.py --list

问题 3：语音合成失败

可能原因：

• 音色状态不是 OK
• 文本过长
• 网络问题

解决：

1. 检查音色状态：python scripts/voice_clone.py --list
2. 缩短文本长度
3. 检查网络连接

问题 4：文件上传失败

可能原因：

• 文件路径不正确
• 文件格式不支持
• 文件过大

解决：

1. 确认文件路径正确（使用绝对路径）
2. 转换为 MP3 或 WAV 格式
3. 确保文件大小合理（< 10MB）

📁 相关文件

文件	说明
scripts/voice_clone.py	主脚本，包含所有功能实现
references/api.md	API 详细文档，包含接口说明
.env	环境配置文件（需自行创建）

📚 API 接口速查

接口	方法	说明
/ai/voice/clone/list	GET	查询音色列表
/ai/voice/clone/sync/create	POST	创建新音色
/ai/voice/clone/synthesize	POST	语音合成
/system/fileUpload/upload	POST	文件上传

详细 API 文档请查看 references/api.md

🎯 后续扩展

本技能支持以下扩展场景：

• 批量合成 - 循环调用合成接口生成多个语音文件
• 音色管理 - 添加删除、重命名音色的功能
• 音频处理 - 集成音频剪辑、合并功能
• Web 界面 - 构建图形化操作界面
• API 服务 - 封装为 REST API 供其他系统调用

---

如有问题或建议，请联系技能维护者。