七色堇音乐开放 API 文档

01

快速开始

无需申请新的 Token，直接沿用会员中心内已有的 API Key。

1获取 API Key

登录后进入「会员信息 → API 接口」，点击“获取我的 API 密钥”。

2设置认证头

在每个请求中带上 Authorization: Bearer YOUR_API_KEY。

3提交异步任务

上传音频时指定对应能力模型，例如 model=qisejin-Q1-transcribe。

提示：API Key 只在你的服务端保存和使用，不要写进网页、移动端安装包、截图或公开仓库。

POST/v1/audio/tasks

BASE="https://audio.livepartner.fans/v1"
QISE_API_KEY="YOUR_QISE_API_KEY"

curl "$BASE/audio/tasks" \
  -H "Authorization: Bearer $QISE_API_KEY" \
  -F "model=qisejin-Q1-transcribe" \
  -F "file=@song.mp3"

先确认这三点：请求地址必须以 https://audio.livepartner.fans/v1 为 Base URL；上传音频必须使用 multipart/form-data（cURL 用 -F，不要手写 JSON）；提交后请原样使用返回的完整 poll_url 查询，不能改成 /v1/suno/...、/v1/act/... 或其它供应商路径。

最小可用性测试（不会创建任务）：

BASE="https://audio.livepartner.fans/v1"
curl "$BASE/models" -H "Authorization: Bearer $QISE_API_KEY"
curl "$BASE/balance" -H "Authorization: Bearer $QISE_API_KEY"

两次请求都返回 200 后，再提交音频任务。返回 401/403 时先处理账号权限或 Key，不要重复提交。

02

认证与 API Base

沿用原 API Key；无需换 Key、无需额外登录。

API Basehttps://audio.livepartner.fans/v1

请求头Authorization: Bearer YOUR_API_KEY

也兼容 X-API-Key: YOUR_API_KEY。如同时携带两种认证头，系统优先使用 Authorization。请只通过 HTTPS 调用。

品牌出品配置API Key 不变，成果可使用客户品牌

在会员中心的「API 接口」页面，可为该 Key 设置客户标识、公开 HTTPS Logo 地址和出品／水印文字。通过此 Key 生成的乐谱、歌词与嵌入播放器会使用该品牌，不会默认显示七色堇；站内其它成果不受影响。

该配置仅在会员中心中管理，不是 Bearer /v1 调用接口；请勿把品牌配置或 Key 暴露给前端用户。

03

模型列表

使用统一模型列表格式，便于 SDK 和服务端探活。

GET/v1/models

返回当前 Key 可调用的能力模型。每个处理能力都有独立的 qisejin-Q1-* 模型 ID，便于供应商控制台按能力绑定。

curl "$BASE/models" \
  -H "Authorization: Bearer $QISE_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "qisejin-Q1-accompaniment",
      "name": "qisejin-Q1-accompaniment",
      "object": "model",
      "owned_by": "qisejin",
      "root": "qisejin-Q1",
      "operation": "accompaniment",
      "capabilities": {
        "audio_tasks": {
          "status": "available",
          "operations": ["accompaniment"]
        }
      }
    }
  ]
}

获取单个模型：GET /v1/models/qisejin-Q1-accompaniment。音频能力模型包括 qisejin-Q1-accompaniment、qisejin-Q1-transcribe、qisejin-Q1-separate、qisejin-Q1-tune、qisejin-Q1-quality、qisejin-Q1-denoise、qisejin-Q1-lyrics 与 qisejin-Q1-reverse。

模型名称规则：每项音频能力均使用对应的 qisejin-Q1-* 子模型。operation 可省略；若传入，必须与模型尾缀一致。旧模型 qisejin-Q1 已废弃，调用会返回 410 model_deprecated。

04

余额查询

调用前可查询当前 API 账户可用点数，便于在你的产品中提示用户。

GET/v1/balance

不会扣点。支持 Authorization: Bearer 与 X-API-Key；available_points 为当前可用总点数，赠送点数会优先被消耗。

请求

curl "$BASE/balance" \
  -H "Authorization: Bearer $QISE_API_KEY"

返回示例

{
  "object": "balance",
  "currency": "points",
  "available_points": 320,
  "gifted_points": 120,
  "purchased_points": 200
}

补充账务查询：GET /v1/dashboard/billing/credit_grants 也可返回 total_available，适合需要统一余额字段的项目。

点数规则：赠送点数按 UTC 月初重置，充值点数不受影响；执行任务时会优先扣除赠送点数，再扣除充值点数。

05

提交音乐任务

以统一的异步任务接口上传音频；每项能力使用自己的 qisejin-Q1-* 子模型。

POST/v1/audio/tasks

请求类型为 multipart/form-data。成功提交后立即返回任务对象，请使用返回的 poll_url 轮询进度和下载结果。

字段	类型	必填	说明
`model`	string	是	填写能力模型，例如 `qisejin-Q1-transcribe`。
`operation`	string	否	可省略；传入时必须与模型尾缀相同。
`file`	file	除 tune 外必填	待处理的音频文件；支持 MP3、WAV、FLAC、M4A、OGG、AAC。
`performance`	file	仅 tune 必填	AI 修音时使用的待修人声音频；tune 不需要上传 `file`。
`reference`	file	仅 tune	可选的原唱参考音频；不传时按待修人声自动校正。

curl "$BASE/audio/tasks" \
  -H "Authorization: Bearer $QISE_API_KEY" \
  -F "model=qisejin-Q1-transcribe" \
  -F "file=@song.mp3"

{
  "id": "task_qise_xxx",
  "object": "audio.task",
  "model": "qisejin-Q1-transcribe",
  "operation": "transcribe",
  "status": "queued",
  "poll_url": "https://audio.livepartner.fans/v1/audio/tasks/task_qise_xxx"
}

accompaniment伴奏提取

transcribe歌曲转谱

separate六轨分离

quality音质提升

denoise音频降噪

lyrics逐字歌词

reverse逆向分析

tuneAI 修音

能力参数：qisejin-Q1-quality 与 qisejin-Q1-denoise 可附带 processing_model、lowpass、steps（接口接受 1–200，服务端实际按 10–200 执行）、seed；降噪模型另可使用 strength（接口接受 0–100，服务端实际按 4–30 执行）。当前版本仅支持轮询，不支持 callback_url。

POSTAI 修音示例

AI 修音对应模型为 qisejin-Q1-tune；待修人声使用 performance 字段，可选 reference 原唱参考音频。

curl "$BASE/audio/tasks" \
  -H "Authorization: Bearer $QISE_API_KEY" \
  -F "model=qisejin-Q1-tune" \
  -F "performance=@vocal.wav" \
  -F "reference=@original.wav"

POST能力直连接口（兼容方式）

以下路径与统一入口使用同一套 Bearer API Key、会员权限、点数扣除和异步队列。它们适合已经按能力拆分路由的客户；新接入优先使用上面的 /v1/audio/tasks。直连接口的能力由 URL 固定，因此可省略 model 和 operation，请求仍必须是 multipart/form-data。

路径	能力	文件字段
`/v1/accompaniment`	伴奏提取	`file`
`/v1/transcribe`	歌曲转谱	`file`
`/v1/separate`	六轨分离	`file`
`/v1/quality`	音质提升	`file`
`/v1/denoise`	音频降噪	`file`
`/v1/lyrics`	逐字歌词	`file`
`/v1/reverse`	逆向分析	`file`
`/v1/tune`	AI 修音	`performance`（可选 `reference`）

curl "$BASE/accompaniment" \
  -H "Authorization: Bearer $QISE_API_KEY" \
  -F "file=@song.mp3"

# tune 使用 performance，不使用 file
curl "$BASE/tune" \
  -H "Authorization: Bearer $QISE_API_KEY" \
  -F "performance=@vocal.wav"

返回格式：直连接口返回与统一入口相同的 audio.task 任务对象；请直接使用响应中的完整 poll_url，不要自行拼接任务地址。

06

查询任务结果

音乐处理为异步任务。提交成功后按返回的 poll_url 进行轮询，直到任务完成或失败。

GET/v1/audio/tasks/{id}

建议每隔 2 至 5 秒查询一次。完成后结果会出现在 results 中；下载结果时也必须继续携带同一个 Authorization: Bearer 请求头，不应把结果地址当作公开裸链接。

请求

curl "$BASE/audio/tasks/task_qise_xxx" \
  -H "Authorization: Bearer $QISE_API_KEY"

完成后的返回示例

{
  "id": "task_qise_xxx",
  "object": "audio.task",
  "status": "completed",
  "progress": 100,
  "results": { "audio": "https://…" },
  "estimated_cost_points": 1
}

状态说明：queued 表示已进入队列；running 表示正在处理；completed 表示可下载；failed 时请读取 error 后向用户展示简短提示。

轮询地址不可改写：提交响应里的 poll_url 已包含正确的任务编号和版本路径。请直接 GET 这个完整地址并继续携带同一个认证头；不要根据任务编号拼接旧的 /v1/suno/act/timing/{id} 或其它路径，这些地址不属于七色堇 API，会返回 404 endpoint_not_found。

账务状态：completed 仅表示处理已完成，并不代表点数已在该时刻扣除。请以 billing.charge_status 为准：pending_on_success 表示等待按成功结果结算，pending_reconciliation 表示正在对账，charged 表示已实际扣点；失败任务会返回 not_charged。

07

qisejin-Q1-chat 音乐智能助手

用于文本问答、音乐创作建议与结构化文案输出；采用七色堇聊天接口格式，不替代异步音乐处理任务。

POST/v1/chat/completions

请求和返回均为统一 API JSON。模型填写 qisejin-Q1-chat；该模型仅在后台启用智能助手后出现在模型列表中。

支持	范围 / 说明
`messages`	必填；支持 `system`、`developer`、`user`、`assistant` 四种角色，单次最多 64 条文本消息。
`temperature` / `top_p`	分别支持 `0–2` 与 `0–1`；还支持 `presence_penalty`、`frequency_penalty`。
`max_tokens`	也兼容 `max_completion_tokens`，范围为 `1–16384`；每次仅支持 `n=1`。
`response_format` / `stream`	支持 `text`、`json_object` 与流式 SSE 响应；流式结果可能在服务完成生成后以内容块返回。

curl "$BASE/chat/completions" \
  -H "Authorization: Bearer $QISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qisejin-Q1-chat",
    "messages": [
      {"role": "user", "content": "给出一首流行歌曲的编曲建议"}
    ],
    "temperature": 0.4
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "qisejin-Q1-chat",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "…"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

启用条件：只有平台后台已启用并完整配置“大模型服务”后，智能助手才可调用；未配置时会返回 503 和 model_not_configured。音频任务接口不依赖该配置。

暂不支持：工具调用 tools / functions、图片或音频消息等非文本内容。需要处理音频文件时，请使用上方异步音乐任务接口。

08

Python 与 JavaScript 接入

音乐任务为标准 multipart 上传与 HTTP 轮询；下面示例可直接放进你的服务端。

Python

import os
import time
import requests

BASE = "https://audio.livepartner.fans/v1"
headers = {"Authorization": f"Bearer {os.environ['QISE_API_KEY']}"}

with open("song.mp3", "rb") as audio:
    task = requests.post(
        f"{BASE}/audio/tasks",
        headers=headers,
        data={"model": "qisejin-Q1-transcribe"},
        files={"file": audio},
        timeout=120,
    ).json()

while task["status"] not in {"completed", "failed"}:
    time.sleep(3)
    task = requests.get(task["poll_url"], headers=headers, timeout=30).json()

if task["status"] == "completed":
    print(task["results"])
else:
    print("任务未完成，请稍后重试")

JavaScript

import { readFile } from "node:fs/promises";

const base = "https://audio.livepartner.fans/v1";
const headers = { Authorization: `Bearer ${process.env.QISE_API_KEY}` };
const form = new FormData();
form.set("model", "qisejin-Q1-transcribe");
form.set("file", new Blob([await readFile("song.mp3")]), "song.mp3");

let task = await fetch(`${base}/audio/tasks`, {
  method: "POST", headers, body: form,
}).then((res) => res.json());

while (!["completed", "failed"].includes(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  task = await fetch(task.poll_url, { headers }).then((res) => res.json());
}

console.log(task.status === "completed" ? task.results : "任务未完成，请稍后重试");

Python SDK 调用智能助手

from openai import OpenAI

client = OpenAI(api_key="YOUR_QISE_API_KEY", base_url="https://audio.livepartner.fans/v1")
reply = client.chat.completions.create(
    model="qisejin-Q1-chat",
    messages=[{"role": "user", "content": "给出歌曲的编曲建议"}],
)
print(reply.choices[0].message.content)

Python 音频任务示例需要 pip install requests；智能助手可使用 pip install openai。生产环境请从环境变量读取 API Key。

09

错误与安全建议

所有错误均返回 JSON；请按状态码处理，并向最终用户展示友好提示。

401密钥无效

返回 invalid_api_key 时，检查 Bearer 前缀、Key 是否完整、是否复制了空格或引号，以及 Key 是否仍有效。

403暂无接口权限

返回 insufficient_permissions 时，Key 本身可识别但账号未开通或已到期 API 会员；需在会员中心开通 API 资格。

402可用点数不足

响应会提供 available_points、required_points 与 shortage_points；据此提示用户充值后再试。

400上传格式错误

返回 invalid_content_type 时，说明请求没有使用 multipart/form-data；请使用文档中的 cURL -F 或 SDK 的 files/FormData。

404接口地址错误

返回 endpoint_not_found 时，通常是调用了旧的 /v1/suno/...、/v1/act/... 路径。请使用统一入口 /v1/audio/tasks 或本文列出的能力直连接口。

503服务暂不可用

智能助手未配置时返回 model_not_configured；音频队列或存储暂不可用时请稍后重试，不要重复创建同一任务。

将 API Key 存在服务端环境变量，例如 QISE_API_KEY；不要放在浏览器代码中。
不要记录完整 API Key 到日志、埋点、错误上报或客服截图中。
当返回失败时，展示简短业务提示；不要把接口原始报错直接透传给终端用户。

把音乐能力接进你的产品

快速开始

认证与 API Base

模型列表

余额查询

提交音乐任务

查询任务结果

qisejin-Q1-chat 音乐智能助手

Python 与 JavaScript 接入

错误与安全建议

准备好接入了吗？