返回 API 入口

Public API · v1

气泡音 API 文档

面向服务端的音视频处理接口。所有任务使用同一套 Key 认证、异步生命周期、账户余额和安全下载规则。

Base URL
https://www.qipaoyin.com/api/v1

快速开始

先在 /api 创建 Key,再选择一种服务端语言提交任务。下列示例均完成同一项人声与伴奏分离。

cURL
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"
Python · requests
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)
Node.js · native fetch
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. 1提交POST 处理接口,成功时收到 202、任务 id 和 queued 状态。
  2. 2轮询每 2–5 秒 GET /jobs/{job_id},并在 429 时按 Retry-After 退避。
  3. 3终态succeeded、failed、canceled 为终态;progress 仅用于多阶段进度提示。
  4. 4下载使用 artifacts[].download_url 或 artifacts.zip;签名下载无需再次携带 Key。

接口参考

下列目录是承诺支持的 Public API,所有路径均以 https://www.qipaoyin.com 开头。Nginx 对 jobs、account/quota、operation-presets 之外的版本化命名空间返回 404;不要依赖目录外路径的状态码或行为。

账户与预设

先确认账户可用额度,并从服务端读取当前公开的处理预设。

GET
/api/v1/account/quota

读取共享余额、每日额度和当前 Key ID

GET
/api/v1/operation-presets

列出分离与降噪可使用的产品预设

任务生命周期

所有处理任务均采用提交、轮询、下载的异步流程。

GET
/api/v1/jobs

列出当前账户的任务历史

Query: limit, status, operation

GET
/api/v1/jobs/{job_id}

查询一个任务及其公开产物

Path: job_id

POST
/api/v1/jobs/{job_id}/cancel

取消仍在排队的任务

Path: job_id

POST
/api/v1/jobs/{job_id}/delete

删除已完成或失败的任务和留存文件

Path: job_id

POST
/api/v1/jobs/{job_id}/reprocess

按原公开参数重新处理任务

Path: job_id

GET
/api/v1/jobs/{job_id}/artifacts.zip

下载任务的全部产物

Path: job_id

处理能力

上传素材或提交 URL,获得一个可轮询的处理任务。

POST
/api/v1/jobs/separate

按公开预设执行人声、多轨或专业分离

multipart: file, profile_id, original_filename?

POST
/api/v1/jobs/denoise

按公开预设执行音频降噪

multipart: file, profile_id, original_filename?

POST
/api/v1/jobs/midi

把上传的单轨音频转写为 MIDI

multipart: file, stem, original_filename?

POST
/api/v1/jobs/extract-audio

从上传的视频中提取音频

multipart: file, original_filename?

POST
/api/v1/jobs/extract-audio/from-url

从支持的视频链接提取音频

JSON: { "url": "https://..." }

POST
/api/v1/jobs/cut-audio

一次调用完成保留片段裁剪与导出

multipart: file, segments(JSON), fades?, output_format?

结果派生处理

从已完成任务的一个公开产物继续生成专业结果。

POST
/api/v1/jobs/{job_id}/midi

把一个音轨产物转写为 MIDI

JSON: artifact_name, stem?

POST
/api/v1/jobs/{job_id}/overlapping-voices

把人声音轨分离为重叠说话人

JSON: artifact_name, speaker_count

POST
/api/v1/jobs/{job_id}/harmony

从人声音轨分离主唱与和声

JSON: artifact_name, harmony_mode

POST
/api/v1/jobs/{job_id}/chorus-gender

从合唱人声音轨分离男女声

JSON: artifact_name

Common Tools

编辑类能力先准备素材,再读取安全元数据,最后提交渲染参数。

POST
/api/v1/jobs/edit-audio

准备音频裁剪源

multipart: file, original_filename?

POST
/api/v1/jobs/{job_id}/edit-audio

从已有任务产物准备音频裁剪源

JSON: artifact_name

GET
/api/v1/jobs/{job_id}/edit-audio/source

读取裁剪源、波形和精度信息

Path: job_id

POST
/api/v1/jobs/{job_id}/edit-audio/render

按保留区间渲染裁剪结果

JSON: segments, fades, output_format

POST
/api/v1/jobs/adjust-audio

准备音量、速度与音高调节源

multipart: file, original_filename?

POST
/api/v1/jobs/{job_id}/adjust-audio

从已有任务产物准备音频调节源

JSON: artifact_name

GET
/api/v1/jobs/{job_id}/adjust-audio/source

读取调节源和波形信息

Path: job_id

POST
/api/v1/jobs/{job_id}/adjust-audio/render

渲染音量、速度与音高变更

JSON: volume_db, speed, pitch_semitones, output_format

POST
/api/v1/jobs/convert-audio

准备格式转换源

multipart: file, original_filename?

POST
/api/v1/jobs/{job_id}/convert-audio

从已有任务产物准备格式转换源

JSON: artifact_name

GET
/api/v1/jobs/{job_id}/convert-audio/source

读取转换源格式与时长

Path: job_id

POST
/api/v1/jobs/{job_id}/convert-audio/render

渲染目标音频格式

JSON: output_format

POST
/api/v1/jobs/join-audio/sources

逐个准备拼接音频源

multipart: file, original_filename?

GET
/api/v1/jobs/{job_id}/join-audio/source

读取一个新拼接源

Path: job_id

POST
/api/v1/jobs/join-audio/render

首次渲染多个准备好的拼接源

JSON: clips[source_job_id...], output_format

GET
/api/v1/jobs/{job_id}/join-audio/project

读取已完成的拼接项目

Path: job_id

POST
/api/v1/jobs/{job_id}/join-audio/render

继续渲染已有拼接项目

JSON: clips[source_id...], output_format

参数与编码

产品预设

分离和降噪先调用 GET /operation-presets,再把返回的preset_id作为profile_id。Key 请求只接受fileprofile_id和可选original_filename;模型、设备、采样率、 输出覆盖、separator kwargs 和 pipeline metadata 均被拒绝。

multipart 中的 JSON 字段

一次调用裁剪的 segments 是 JSON 数组字符串, 不是重复 form 字段。区间必须按源时间线有序、不重叠,每项包含start_secondsend_seconds

One-call cut
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_iduser_id兼容字段固定为 null。 download_url 是站点根相对签名链接,应与站点 Origin 组合,不能改写为 /api/v1; 错误改写后的版本化 jobs 路径仍受 Key 入口检查,可能返回 401。

Job response · abbreviated
{
  "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 + 每 IP5 r/s10
POST:每 Key + 每 IP1 r/s5
签名下载:每 IP5 r/s10

429 响应包含 rate_limitedRetry-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
文档描述当前 v1 产品合同。接口发生兼容性变化时将通过新的版本路径发布。