chanjing-tts-voice-clone

Chanjing TTS Voice Clone

功能说明

基于用户提供的参考音频公网 URL（由蝉镜服务端拉取）创建音色并合成语音；轮询任务并从接口返回的 URL 下载结果。脚本不依赖 ffmpeg/ffprobe。凭据、令牌写回与权限见 manifest.yaml；刷新时会覆盖同一文件中的 access_token / expire_in 字段，勿将凭证提交到版本库。

运行依赖

• python3 与同仓库 scripts/*.py
• 无 ffmpeg/ffprobe 门控

环境变量与机器可读声明

• 环境变量键名与说明：manifest.yaml（environment 段）及本文
• 变量、凭据、permissions.userContent（含由蝉镜拉取的参考音公网 URL）：manifest.yaml

使用命令

• ClawHub（slug 以注册表为准）：clawhub run chanjing-tts-voice-clone
• 本仓库：python skills/chanjing-tts-voice-clone/scripts/create_voice.py …（见正文 How to Use）

---

登记与审稿（单一事实来源）

主凭据、expire_in 写回与覆盖行为、用户参考音 URL 边界等：以 manifest.yaml 为准。本文从 How to Use 开始介绍 API 步骤与英文接口说明。

何时使用此技能

当用户需要使用其提供的参考音色生成语音时，请使用此技能。参考音频必须提供可公开访问的 URL。

此 TTS 服务支持：

• 中英文双语
• 调整语速
• 句子级时间戳

如何使用此技能

前置条件（权限验证）：执行此 Skill 前，必须先通过 chanjing-credentials-guard 完成 AK/SK 与 Token 校验。脚本与 guard 使用同一套凭证；无凭证时会执行 open_login_page.py 打开注册/登录页。凭据与审稿对表见 manifest.yaml。

安全与凭据（引用）

用途 / 凭据 / 用户提供的参考 URL / 下载：见 manifest.yaml 中的 credentials 与 clientPermissions（及合规 permissions）；请勿与本节以下 API 文档重复维护表格。

Chanjing-TTS-Voice-Clone 提供异步语音合成 API。 所有 API 的主机名为："https://open-api.chanjing.cc"。 所有请求均使用 JSON 通信。 请在整个任务中使用 UTF-8 对文本进行编码和解码。

1. 获取后续请求所需的 access_token
2. 调用 Create Voice API，提供音频文件 URL 作为参考音色
3. 轮询 Query Voice API，直到结果成功；保留 voice ID
4. 调用 Create Speech Generation Task API，使用 voice ID，并记录 task_id
5. 轮询 Query Speech Generation Task Status API，直到结果成功
6. 任务状态完成后，使用 API 响应中的相应 URL 下载生成的音频文件

获取 Access Token API

从 ~/.chanjing/credentials.json 读取 app_id 和 secret_key；若无有效 Token，则调用：

POST /open/v1/access_token
Content-Type: application/json

请求体（使用本地配置的 app_id、secret_key）：

{
  "app_id": "<从 credentials.json 读取>",
  "secret_key": "<从 credentials.json 读取>"
}

响应示例：

{
  "trace_id": "8ff3fcd57b33566048ef28568c6cee96",
  "code": 0,
  "msg": "success",
  "data": {
    "access_token": "1208CuZcV1Vlzj8MxqbO0kd1Wcl4yxwoHl6pYIzvAGoP3DpwmCCa73zmgR5NCrNu",
    "expire_in": 1721289220
  }
}

响应字段说明：

一级字段	二级字段	说明
code		响应状态码
msg		响应消息
data		响应数据
	access_token	有效期为一天，之前的 Token 将失效
	expire_in	Token 过期时间

响应状态码说明：

code	说明
0	成功
400	参数格式错误
40000	参数错误
50000	系统内部错误

创建音色 API

向以下端点发送 POST 请求以创建音色。

POST /open/v1/create_customised_audio
access_token: {{access_token}}
Content-Type: application/json

请求体示例：

{
  "name": "example",
  "url": "https://example.com/abc.mp3"
}

请求字段说明：

字段	类型	必填	说明
name	string	是	此音色的名称
url	string	是	参考音频文件的 URL，格式必须为 mp3、wav 或 m4a。支持的 MIME 类型：audio/x-wav、audio/mpeg、audio/m4a、video/mp4。大小不得超过 100MB。建议音频时长：30s-5min
model_type	string	是	使用 "Cicada3.0-turbo"
language	string	否	可选 "cn" 或 "en"，默认为 "cn"

响应示例：

{
  "trace_id": "2f0f50951d0bae0a3be3569097305424",
  "code": 0,
  "msg": "success",
  "data": "C-Audio-53e4e53ba1bc40de91ffaa74f20470fc"
}

响应字段说明：

字段	说明
code	状态码
msg	消息
data	音色 ID，用于后续步骤

响应状态码说明：

Code	说明
0	成功
400	参数格式错误
10400	AccessToken 错误
40000	参数错误
40001	超出 QPS 限制
50000	系统内部错误

查询声音 API

向以下端点发送 GET 请求，查询声音是否已准备就绪。声音 ID 在上一步获取。 轮询过程可能需要几分钟，请持续轮询，直到状态表示声音已准备就绪。

GET /open/v1/customised_audio?id={{voice_id}}
access_token: {{access_token}}

响应示例：

{
  "trace_id": "7994cedae0f068d1e9e4f4abdf99215b",
  "code": 0,
  "msg": "success",
  "data": {
    "id": "C-Audio-53e4e53ba1bc40de91ffaa74f20470fc",
    "name": "声音克隆",
    "type": "cicada1.0",
    "progress": 0,
    "audio_path": "",
    "err_msg": "不支持的音频格式，请阅读接口文档",
    "status": 2
  }
}

响应字段说明：

一级字段	二级字段	说明
code		状态码
msg		响应消息
data
	id	声音 ID
	progress	进度：范围为 0-100
	type
	name
	err_msg	错误消息
	audio_path
	status	0-排队中；1-进行中；2-已完成；3-已过期；4-失败；99-已删除

响应状态码说明：

代码	说明
0	成功
10400	AccessToken 错误
40000	参数错误
40001	超出 QPS 限制
50000	系统内部错误

创建语音生成任务 API

向以下端点发送 POST 请求，提交语音生成任务：

POST /open/v1/create_audio_task
access_token: {{access_token}}
Content-Type: application/json

请求体示例：

{
  "audio_man": "C-Audio-53e4e53ba1bc40de91ffaa74f20470fc",
  "speed": 1,
  "pitch": 1,
  "text": {
    "text": "Hello, I am your AI assistant."
  }
}

请求字段说明：

参数名称	类型	嵌套键	必填	示例	说明
audio_man	string		是	C-Audio-53e4e53ba1bc40de91ffaa74f20470fc	声音 ID，在上一步获取
speed	number		是	1	语速，范围：0.5（慢）至 2（快）
pitch	number		是	1	音高（始终设为 1）
text	object	text	是	Hello, I am your Cicada digital human	富文本，文本长度限制为少于 4,000 个字符
aigc_watermark	bool		否	false	是否为音频添加可见水印，默认为 false

响应字段说明：

字段	说明
code	响应状态码
msg	响应消息
task_id	语音合成任务 ID

响应示例

{
  "trace_id": "dd09f123a25b43cf2119a2449daea6de",
  "code": 0,
  "msg": "success",
  "data": {
    "task_id": "88f635dd9b8e4a898abb9d4679e0edc8"
  }
}

响应状态码说明：

code	说明
0	成功
400	输入参数格式错误
10400	AccessToken 验证失败
40000	参数错误
40001	超出 QPS 限制
40002	生成时长达到上限
50000	系统内部错误

查询语音生成任务状态 API

向以下端点发送请求：

POST /open/v1/audio_task_state
access_token: {{access_token}}
Content-Type: application/json

请求体示例：

{
  "task_id": "88f635dd9b8e4a898abb9d4679e0edc8"
}

请求字段说明：

参数名称	类型	必填	示例	说明
task_id	string	是	88f789dd9b8e4a121abb9d4679e0edc8	在上一步获取的任务 ID

响应体示例：

{
  "trace_id": "ab18b14574bbcc31df864099d474080e",
  "code": 0,
  "msg": "success",
  "data": {
    "id": "9546a0fb1f0a4ae3b5c7489b77e4a94d",
    "type": "tts",
    "status": 9,
    "text": [
      "猫在跌落时能够在空中调整身体，通常能够四脚着地，这种”猫右自己“反射显示了它们惊人的身体协调能力和灵活性。核磁共振成像技术通过利用人体细胞中氢原子的磁性来生成详细的内部图像，为医学诊断提供了重要工具。"
    ],
    "full": {
      "url": "https://cy-cds-test-innovation.cds8.cn/chanjing/res/upload/tts/2025-04-08/093a59021d85a72d28a491f21820ece4.wav",
      "path": "093a59013d85a72d28a491f21820ece4.wav",
      "duration": 18.81
    },
    "slice": null,
    "errMsg": "",
    "errReason": "",
    "subtitles": [
      {
        "key": "20c53ff8cce9831a8d9c347263a400a54d72be15",
        "start_time": 0,
        "end_time": 2.77,
        "subtitle": "猫在跌落时能够在空中调整身体"
      },
      {
        "key": "e19f481b6cd2219225fa4ff67836448e054b2271",
        "start_time": 2.77,
        "end_time": 4.49,
        "subtitle": "通常能够四脚着地"
      },
      {
        "key": "140beae4046bd7a99fbe4706295c19aedfeeb843",
        "start_time": 4.49,
        "end_time": 5.73,
        "subtitle": "这种，猫右自己"
      },
      {
        "key": "e851881271876ab5a90f4be754fde2dc6b5498fd",
        "start_time": 5.73,
        "end_time": 7.97,
        "subtitle": "反射显示了它们惊人的身体"
      },
      {
        "key": "fbb0b4138bad189b9fc02669fe1f95116e9991b4",
        "start_time": 7.97,
        "end_time": 9.45,
        "subtitle": "协调能力和灵活性"
      },
      {
        "key": "f73404d135feaf84dd8fbea13af32eac847ac26d",
        "start_time": 9.45,
        "end_time": 12.49,
        "subtitle": "核磁共振成像技术通过利用人体"
      },
      {
        "key": "e18827931223962e477b14b2b8046947039ac222",
        "start_time": 12.49,
        "end_time": 14.77,
        "subtitle": "细胞中氢原子的磁性来生成"
      },
      {
        "key": "d137bf2b0c8b7a39e3f6753b7cf5d92bd877d2d9",
        "start_time": 14.77,
        "end_time": 15.97,
        "subtitle": "详细的内部图像"
      },
      {
        "key": "0773911ae0dbaa763a64352abdb6bdac3ff8f149",
        "start_time": 15.97,
        "end_time": 18.41,
        "subtitle": "为医学诊断提供了重要工具"
      }
    ]
  }
}

响应字段说明：

一级字段	二级字段	三级字段	说明
code			响应状态码
msg			响应消息
data	id		音频 ID
	type		语音类型
	status		状态：1 - 进行中，9 - 已完成
	text		语音文本
	full	url	生成的音频文件下载 URL
		path
		duration	音频时长
	slice
	errMsg		错误消息
	errReason		错误原因
	subtitles(array type)	key	字幕 ID
		start_time	字幕起始时间点
		end_time	字幕结束时间点
		subtitle	字幕文本

响应字段说明：

代码	说明
0	响应成功
10400	AccessToken 验证失败
40000	参数错误
50000	系统内部错误

脚本

本 Skill 提供脚本（skills/chanjing-tts-voice-clone/scripts/），与 chanjing-credentials-guard 使用同一配置文件；无 AK/SK 时会执行 open_login_page.py 脚本打开注册/登录页。

脚本	说明
create_voice.py	提交定制声音任务（参考音频 URL），输出 voice_id
poll_voice.py	轮询定制声音直至就绪（status=2），输出 voice_id
create_task.py	使用定制声音创建 TTS 任务，输出 task_id
poll_task.py	轮询 TTS 任务直至完成，输出音频下载 URL

示例（在项目根目录或 skill 目录下执行）：

# 1. 创建定制声音（参考音频需为公开 URL）
VOICE_ID=$(python skills/chanjing-tts-voice-clone/scripts/create_voice.py --name "我的声音" --url "https://example.com/ref.mp3")

# 2. 轮询直到声音就绪
python skills/chanjing-tts-voice-clone/scripts/poll_voice.py --voice-id "$VOICE_ID"

# 3. 创建 TTS 任务
TASK_ID=$(python skills/chanjing-tts-voice-clone/scripts/create_task.py --audio-man "$VOICE_ID" --text "Hello, I am your AI assistant.")

# 4. 轮询到完成，得到音频下载链接
python skills/chanjing-tts-voice-clone/scripts/poll_task.py --task-id "$TASK_ID"