KUNXUN API 文档

接口目录

网关 v3 核心请求

客户端标识头为 X-Client-Platform 与 X-Client-Key。需要用户身份的请求还须带 Authorization: Bearer <用户令牌>。账号网页登录仍从统一账号中心完成。

真寻配音 API v2 — 构造请求示例

基础信息

0. 先选模型

三种模式中，文本配音和音频变声需要指定模型，人声分离不需要模型。模型列表用下面这个接口拿（全部可用模型都会返回）：

GET /v2/models 需密钥

curl -s https://api.kunxun.top/v2/models \
  -H "Authorization: Bearer YOUR_API_KEY" \

响应示例（返回 id 就是提交任务时要填的 model_id）：

{
  "code": 0,
  "device": "cpu",
  "models": [
    {"id": "onimai_mahiro",  "label": "绪山真寻",   "backend": "rvc", "sampling_rate": 40000, "available": true},
    {"id": "onimai_asahi",   "label": "旭",         "backend": "svc", "sampling_rate": 40000, "available": true},
    {"id": "onimai_kaede",   "label": "枫",         "backend": "svc", "sampling_rate": 40000, "available": true},
    {"id": "onimai_meiboli", "label": "美波里",     "backend": "svc", "sampling_rate": 40000, "available": true},
    {"id": "onimai_miyo",    "label": "美夜",       "backend": "svc", "sampling_rate": 40000, "available": true},
    {"id": "onimai_momiji",  "label": "椛",         "backend": "svc", "sampling_rate": 40000, "available": true},
    {"id": "onimai_zhenxun", "label": "真寻(SVC)",  "backend": "svc", "sampling_rate": 40000, "available": true}
  ]
}

1. 文本配音（TTS）

POST /v2/tts异步 输入文字 + 模型 + 高级参数，输出目标角色朗读的语音。

请求体支持 JSON 和 multipart/form-data 两种格式（客户端按自己习惯选一种）。

参数表（高级参数全部可选）

方式 A：JSON 请求体（推荐给客户端）

curl -s -X POST https://api.kunxun.top/v2/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好呀，我是真寻！今天也要加油哦。",
    "model_id": "onimai_mahiro",
    "edge_voice": "zh-CN-XiaoxiaoNeural",
    "rate": "+0%",
    "pitch": "+0Hz",
    "transpose": 0,
    "f0_method": "rmvpe"
  }'

方式 B：multipart/form-data 请求体

curl -s -X POST https://api.kunxun.top/v2/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "text=你好呀，我是真寻！今天也要加油哦。" \
  -F "model_id=onimai_mahiro" \
  -F "edge_voice=zh-CN-XiaoxiaoNeural" \
  -F "rate=+0%" \
  -F "pitch=+0Hz" \
  -F "transpose=0" \
  -F "f0_method=rmvpe"

提交响应（拿到 job_id 去轮询）

{
  "job_id": "61b05bbc69364cddad1d0daf9069ea4f",
  "kind": "tts",
  "status": "queued",
  "stage": "等待中",
  "progress": 0,
  "queue_position": 1,
  "queue_waiting": 1,
  "model_id": "onimai_mahiro",
  "model_name": "绪山真寻",
  "message": "任务已加入队列",
  "result": {}
}

2. 音频变声（Convert）

POST /v2/convert异步 上传一段音频/视频，把里面的人声转换成目标角色声线。

注意：音频变声是文件上传，请求体必须是 multipart/form-data，不能是 JSON。

参数表

完整构造请求

curl -s -X POST https://api.kunxun.top/v2/convert \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@/path/to/input.mp3" \
  -F "model_id=onimai_mahiro" \
  -F "transpose=0" \
  -F "f0_method=rmvpe"

提交响应

{
  "job_id": "9c2e4f1a8b3d4c5e9f0a1b2c3d4e5f60",
  "kind": "convert",
  "status": "queued",
  "stage": "等待中",
  "progress": 0,
  "queue_position": 1,
  "queue_waiting": 0,
  "model_id": "onimai_mahiro",
  "model_name": "绪山真寻",
  "message": "任务已加入队列",
  "result": {}
}

3. 人声分离（Separate）

POST /v2/separate异步 上传一段混合音频，分离出人声轨和伴奏轨。

特殊：人声分离不需要选模型！它跟角色声线无关，只做「人声 / 伴奏」拆分，所以参数里没有 model_id。

参数表

完整构造请求

curl -s -X POST https://api.kunxun.top/v2/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@/path/to/song.mp3" \
  -F "strength=0.85"

提交响应

{
  "job_id": "7d8e9f0a1b2c3d4e5f60718293a4b5c6d",
  "kind": "separate",
  "status": "queued",
  "stage": "等待中",
  "progress": 0,
  "queue_position": 1,
  "queue_waiting": 0,
  "model_id": "onimai_mahiro",
  "model_name": "绪山真寻",
  "message": "任务已加入队列",
  "result": {}
}

4. 轮询任务结果（三个模式通用）

GET /v2/jobs/{job_id}需密钥 用提交时返回的 job_id 轮询。建议每 2~3 秒查一次，直到 status 变为 succeeded 或 failed。

状态含义：queued 排队中 / running 处理中（progress 是百分比，stage 是当前阶段描述）/ succeeded 完成 / failed 失败（看 message）。

curl 示例

curl -s https://api.kunxun.top/v2/jobs/61b05bbc69364cddad1d0daf9069ea4f \
  -H "Authorization: Bearer YOUR_API_KEY" \

完成响应（succeeded）

{
  "job_id": "61b05bbc69364cddad1d0daf9069ea4f",
  "kind": "tts",
  "status": "succeeded",
  "stage": "完成",
  "progress": 100,
  "elapsed_seconds": 16.85,
  "model_id": "onimai_mahiro",
  "model_name": "绪山真寻",
  "message": "绪山真寻配音生成完成",
  "result": {
    "audio_url": "https://api.kunxun.top/outputs/61b05bbc69364cddad1d0daf9069ea4f.onimai_mahiro.tts.wav",
    "vocals_url": null,
    "background_url": null,
    "duration_seconds": 1.88,
    "model_id": "onimai_mahiro",
    "model_name": "绪山真寻"
  },
  "audio_url": "https://api.kunxun.top/outputs/61b05bbc69364cddad1d0daf9069ea4f.onimai_mahiro.tts.wav"
}

三个模式拿结果的字段对照

Python 轮询示例（客户端常用）

import time
import urllib.request, json

KEY = "YOUR_API_KEY"
BASE = "https://api.kunxun.top/v2"

def poll(job_id, timeout=600):
    url = BASE + "/jobs/" + job_id
    req = urllib.request.Request(url, headers={"Authorization": "Bearer " + KEY})
    start = time.time()
    while time.time() - start < timeout:
        with urllib.request.urlopen(req, timeout=30) as resp:
            data = json.loads(resp.read().decode())
        if data["status"] in ("succeeded", "failed", "error"):
            return data
        time.sleep(3)
    raise TimeoutError("任务超时")

5. 常见错误与排查

其他注意

• Base URL 不要带尾斜杠：https://api.kunxun.top/v2（不是 /v2/）
• 接口只认 API key，不依赖网页登录态；key 在「个人中心」可重新生成，重新生成后旧 key 立即失效
• 所有响应都是 JSON，如果客户端报「Unexpected token <」说明请求路径写错了收到了 HTML，检查 Base URL 拼写
• 单 worker 顺序处理任务：大任务（长音频变声/分离）会占用队列，小任务排队等待属正常现象
• 任务结果文件会保留一段时间，下载要趁早；过期后 job 会返回「任务不存在或已过期」