快速开始
先在 /api 创建 Key,再选择一种服务端语言提交任务。下列示例均完成同一项人声与伴奏分离。
export QIPAOYIN_API_KEY='qpk_...'
curl https://www.qipaoyin.com/api/v1/jobs/separate \
-H "Authorization: Bearer $QIPAOYIN_API_KEY" \
-F "file=@song.wav" \
-F "profile_id=vocal_background"import os
import time
import requests
base = "https://www.qipaoyin.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['QIPAOYIN_API_KEY']}"}
with open("song.wav", "rb") as audio:
response = requests.post(
f"{base}/jobs/separate",
headers=headers,
files={"file": ("song.wav", audio, "audio/wav")},
data={"profile_id": "vocal_background"},
timeout=120,
)
response.raise_for_status()
job = response.json()
while job["status"] not in {"succeeded", "failed", "canceled"}:
time.sleep(3)
job = requests.get(f"{base}/jobs/{job['id']}", headers=headers, timeout=30).json()
print(job)import { openAsBlob } from "node:fs";
const base = "https://www.qipaoyin.com/api/v1";
const headers = {
Authorization: `Bearer ${process.env.QIPAOYIN_API_KEY}`
};
const form = new FormData();
form.set("file", await openAsBlob("./song.wav"), "song.wav");
form.set("profile_id", "vocal_background");
let response = await fetch(`${base}/jobs/separate`, {
method: "POST",
headers,
body: form
});
if (!response.ok) throw new Error(await response.text());
let job = await response.json();
while (!["succeeded", "failed", "canceled"].includes(job.status)) {
await new Promise((resolve) => setTimeout(resolve, 3000));
response = await fetch(`${base}/jobs/${job.id}`, { headers });
job = await response.json();
}
console.log(job);认证与 API Key
API Key 是账户级服务端凭证。普通登录用户最多创建 5 个有效 Key,完整值只在创建时显示一次。
推荐请求头
Authorization: Bearer qpk_...兼容请求头
X-API-Key: qpk_...不要把 Key 放进浏览器、App、小程序、公开仓库、URL 或日志。缺少 Key 返回401 api_key_required;无效或已撤销 Key 返回401 invalid_api_key。非qpk_前缀的凭证按未提供 Key 处理。
任务生命周期
- 1提交POST 处理接口,成功时收到 202、任务 id 和 queued 状态。
- 2轮询每 2–5 秒 GET /jobs/{job_id},并在 429 时按 Retry-After 退避。
- 3终态succeeded、failed、canceled 为终态;progress 仅用于多阶段进度提示。
- 4下载使用 artifacts[].download_url 或 artifacts.zip;签名下载无需再次携带 Key。
接口参考
下列目录是承诺支持的 Public API,所有路径均以 https://www.qipaoyin.com 开头。Nginx 对 jobs、account/quota、operation-presets 之外的版本化命名空间返回 404;不要依赖目录外路径的状态码或行为。
账户与预设
先确认账户可用额度,并从服务端读取当前公开的处理预设。
/api/v1/account/quota读取共享余额、每日额度和当前 Key ID
无
/api/v1/operation-presets列出分离与降噪可使用的产品预设
无
任务生命周期
所有处理任务均采用提交、轮询、下载的异步流程。
/api/v1/jobs列出当前账户的任务历史
Query: limit, status, operation
/api/v1/jobs/{job_id}查询一个任务及其公开产物
Path: job_id
/api/v1/jobs/{job_id}/cancel取消仍在排队的任务
Path: job_id
/api/v1/jobs/{job_id}/delete删除已完成或失败的任务和留存文件
Path: job_id
/api/v1/jobs/{job_id}/reprocess按原公开参数重新处理任务
Path: job_id
/api/v1/jobs/{job_id}/artifacts.zip下载任务的全部产物
Path: job_id
处理能力
上传素材或提交 URL,获得一个可轮询的处理任务。
/api/v1/jobs/separate按公开预设执行人声、多轨或专业分离
multipart: file, profile_id, original_filename?
/api/v1/jobs/denoise按公开预设执行音频降噪
multipart: file, profile_id, original_filename?
/api/v1/jobs/midi把上传的单轨音频转写为 MIDI
multipart: file, stem, original_filename?
/api/v1/jobs/extract-audio从上传的视频中提取音频
multipart: file, original_filename?
/api/v1/jobs/extract-audio/from-url从支持的视频链接提取音频
JSON: { "url": "https://..." }
/api/v1/jobs/cut-audio一次调用完成保留片段裁剪与导出
multipart: file, segments(JSON), fades?, output_format?
结果派生处理
从已完成任务的一个公开产物继续生成专业结果。
/api/v1/jobs/{job_id}/midi把一个音轨产物转写为 MIDI
JSON: artifact_name, stem?
/api/v1/jobs/{job_id}/overlapping-voices把人声音轨分离为重叠说话人
JSON: artifact_name, speaker_count
/api/v1/jobs/{job_id}/harmony从人声音轨分离主唱与和声
JSON: artifact_name, harmony_mode
/api/v1/jobs/{job_id}/chorus-gender从合唱人声音轨分离男女声
JSON: artifact_name
Common Tools
编辑类能力先准备素材,再读取安全元数据,最后提交渲染参数。
/api/v1/jobs/edit-audio准备音频裁剪源
multipart: file, original_filename?
/api/v1/jobs/{job_id}/edit-audio从已有任务产物准备音频裁剪源
JSON: artifact_name
/api/v1/jobs/{job_id}/edit-audio/source读取裁剪源、波形和精度信息
Path: job_id
/api/v1/jobs/{job_id}/edit-audio/render按保留区间渲染裁剪结果
JSON: segments, fades, output_format
/api/v1/jobs/adjust-audio准备音量、速度与音高调节源
multipart: file, original_filename?
/api/v1/jobs/{job_id}/adjust-audio从已有任务产物准备音频调节源
JSON: artifact_name
/api/v1/jobs/{job_id}/adjust-audio/source读取调节源和波形信息
Path: job_id
/api/v1/jobs/{job_id}/adjust-audio/render渲染音量、速度与音高变更
JSON: volume_db, speed, pitch_semitones, output_format
/api/v1/jobs/convert-audio准备格式转换源
multipart: file, original_filename?
/api/v1/jobs/{job_id}/convert-audio从已有任务产物准备格式转换源
JSON: artifact_name
/api/v1/jobs/{job_id}/convert-audio/source读取转换源格式与时长
Path: job_id
/api/v1/jobs/{job_id}/convert-audio/render渲染目标音频格式
JSON: output_format
/api/v1/jobs/join-audio/sources逐个准备拼接音频源
multipart: file, original_filename?
/api/v1/jobs/{job_id}/join-audio/source读取一个新拼接源
Path: job_id
/api/v1/jobs/join-audio/render首次渲染多个准备好的拼接源
JSON: clips[source_job_id...], output_format
/api/v1/jobs/{job_id}/join-audio/project读取已完成的拼接项目
Path: job_id
/api/v1/jobs/{job_id}/join-audio/render继续渲染已有拼接项目
JSON: clips[source_id...], output_format
参数与编码
产品预设
分离和降噪先调用 GET /operation-presets,再把返回的preset_id作为profile_id。Key 请求只接受file、profile_id和可选original_filename;模型、设备、采样率、 输出覆盖、separator kwargs 和 pipeline metadata 均被拒绝。
multipart 中的 JSON 字段
一次调用裁剪的 segments 是 JSON 数组字符串, 不是重复 form 字段。区间必须按源时间线有序、不重叠,每项包含start_seconds和end_seconds。
curl https://www.qipaoyin.com/api/v1/jobs/cut-audio \
-H "Authorization: Bearer $QIPAOYIN_API_KEY" \
-F "file=@song.mp3;type=audio/mpeg" \
-F 'segments=[{"start_seconds":0,"end_seconds":30.5}]' \
-F "fade_in_seconds=0.2" \
-F "output_format=mp3"编辑与拼接 JSON
edit render 接受 1–100 个 segments、0–5 秒 fades 和 mp3/wav/flac;adjust render 接受 volume_db、speed、pitch_semitones 和格式; convert render 接受 output_format;join render 最多接受 10 个 clips,首次使用 source_job_id,继续项目使用 source_id。edit、adjust、convert 也可从已有任务 产物准备源:向对应的POST /jobs/{job_id}/...接口发送 artifact_name。
任务响应与下载
公开响应不会返回模型文件、框架、队列、主机路径或存储键。owner_id与user_id兼容字段固定为 null。 download_url 是站点根相对签名链接,应与站点 Origin 组合,不能改写为 /api/v1; 错误改写后的版本化 jobs 路径仍受 Key 入口检查,可能返回 401。
{
"id": "01J...",
"operation": "separate",
"status": "succeeded",
"owner_id": null,
"user_id": null,
"request": { "profile_id": "vocal_background" },
"artifacts": [
{
"filename": "song(人声).wav",
"display_label": "人声",
"path": "",
"size_bytes": 123456,
"download_url": "/jobs/01J.../artifacts/song...?share_token=..."
}
],
"error": null
}计费与并发
成功后按秒计费
失败和取消不扣额度。分离、降噪、MIDI、提取按输入时长;裁剪和拼接按输出时长; 变速按 source_duration / speed;格式转换按原时长。
与网站共享限制
免费额度先用,再扣分钟余额。同一账户只能有一个计费任务处于 queued/running, 网站与 API 相互占用;冲突返回 409 quota_job_in_progress。
限流与错误
| 范围 | 持续速率 | Burst |
|---|---|---|
| 读取:每 Key + 每 IP | 5 r/s | 10 |
| POST:每 Key + 每 IP | 1 r/s | 5 |
| 签名下载:每 IP | 5 r/s | 10 |
429 响应包含 rate_limited 和Retry-After。其他常见错误: api_key_required、invalid_api_key、api_profile_required、api_parameter_not_allowed、 media_too_large、insufficient_minutes、quota_job_in_progress、source_expired。
安全边界
Public API 仅支持服务端调用
当前不提供 CORS、Webhook、OAuth、独立 API 余额、独立并发池、Swagger、 OpenAPI JSON 或浏览器 Try it。认证、支付、Admin、系统、批量任务和本地上传桥接 不是 Public API;不要探测或依赖未文档化路径。
管理 API Key