灵声妙语开放 API 文档（公测，可能不稳定）

灵声妙语开放 API 提供与 OpenAI Audio API 兼容的语音合成接口，支持零样本声音克隆：voice 直接传入参考音频 URL，无需预先创建角色。

Base URL: https://api2.lsmy.cc/api/v1
协议: HTTPS
认证方式: Bearer Token（API Key）
兼容性: POST /audio/speech 与 OpenAI Audio API 兼容，可用 openai SDK 的 client.audio.speech.create(...) 直接调用

认证

所有请求需在 Header 中携带 API Key：

Authorization: Bearer <your_api_key>

获取 API Key

登录 www.quips.cn
进入「工作台 → 开放 API」页面
创建 / 复制你的 API Key

权限要求：开放 API 仅对付费订阅且套餐包含 API 访问权限的会员开放。免费/未订阅用户调用会返回 403 subscription_required；已订阅但套餐未开放 API 时返回 403 api_access_denied。

认证错误

HTTP	code	说明
401	`missing_api_key`	未携带 API Key
401	`invalid_api_key`	API Key 无效
403	`subscription_required`	未订阅或订阅失效
403	`api_access_denied`	当前套餐不支持 API 访问

端点总览

方法	路径	说明	OpenAI 兼容
POST	`/audio/speech`	语音合成（同步直返音频）	✅
GET	`/models`	列出可用模型	✅

1. 语音合成（OpenAI 兼容）

POST /audio/speech

同步接口：提交文本与参考音频 URL 后，服务端阻塞等待合成完成，直接返回音频字节流（不是 JSON）。响应体即音频文件，Content-Type 由 response_format 决定。

请求体（JSON）

字段	类型	必填	默认	说明
`model`	string	否	`quips-tts-v1`	模型 ID，目前仅支持 `quips-tts-v1`
`input`	string	是	—	要合成的文本内容
`voice`	string	是	—	参考音频 URL（http/https，用于零样本声音克隆）
`response_format`	string	否	`mp3`	音频格式，见下表
`speed`	float	否	`1.0`	语速倍率，范围 `0.25 ~ 4.0`
`ref_text`	string	否	—	参考音频对应文本，提升克隆效果。未提供时自动 ASR 识别参考音频，积分按 ×3 计费
`language`	string	否	`en`	参考音频语言（如 `zh`/`en`/`ja`），传给 ASR；不传默认 `en`（英文模型），传 `zh` 走中文模型

voice 必须为可公网访问的 http/https URL，服务端需能直接拉取。非 URL（如角色 ID）会返回 400 invalid_voice_url。

支持的音频格式

`response_format`	Content-Type	说明
`mp3`	`audio/mpeg`	MP3（默认）
`opus`	`audio/ogg`	Opus（Ogg 容器）
`aac`	`audio/aac`	AAC
`flac`	`audio/flac`	FLAC 无损
`wav`	`audio/wav`	WAV
`pcm`	`audio/pcm`	无头 PCM（s16le, 24kHz, mono）

response_format 大小写不敏感（MP3 等同 mp3）。所有格式统一为 24kHz 单声道；mp3/opus/aac 编码码率 128kbps。

响应

成功（200）：响应体为音频字节流，Content-Type 对应上表。
失败：返回 JSON 错误体（见错误处理）。

cURL 示例

# 提供 ref_text（积分 ×1）
curl -X POST https://api2.lsmy.cc/api/v1/audio/speech \
  -H "Authorization: Bearer $QUIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "quips-tts-v1",
    "input": "你好，欢迎使用灵声妙语。",
    "voice": "https://cdn.example.com/ref.wav",
    "ref_text": "这是参考音频对应的文本。",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3

# 不提供 ref_text（自动 ASR 识别，积分 ×3）
curl -X POST https://api2.lsmy.cc/api/v1/audio/speech \
  -H "Authorization: Bearer $QUIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "quips-tts-v1",
    "input": "你好，欢迎使用灵声妙语。",
    "voice": "https://cdn.example.com/ref.wav",
    "language": "zh"
  }' \
  --output speech.mp3

Python（openai SDK）示例

from openai import OpenAI

client = OpenAI(
    base_url="https://api2.lsmy.cc/api/v1",
    api_key="<your_api_key>",
)

# voice 传参考音频 URL；扩展字段 ref_text/language 通过 extra_body 传入
response = client.audio.speech.create(
    model="quips-tts-v1",
    voice="https://cdn.example.com/ref.wav",
    input="你好，欢迎使用灵声妙语。",
    response_format="mp3",
    speed=1.0,
    extra_body={"ref_text": "这是参考音频对应的文本。"},  # 可选；不传则自动 ASR（积分 ×3）
)

response.write_to_file("speech.mp3")

Node.js（openai SDK）示例

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI({
  baseURL: "https://api2.lsmy.cc/api/v1",
  apiKey: "<your_api_key>",
});

const response = await client.audio.speech.create({
  model: "quips-tts-v1",
  voice: "https://cdn.example.com/ref.wav",
  input: "你好，欢迎使用灵声妙语。",
  response_format: "mp3",
  speed: 1.0,
  // 扩展字段 ref_text/language 直接传入（JS SDK 接受额外字段）
  ref_text: "这是参考音频对应的文本。",
});

fs.writeFileSync("speech.mp3", Buffer.from(await response.arrayBuffer()));

行为说明

同步阻塞：请求会等待 ASR（如需）+ 合成 + 转码完成后返回音频。文本越长等待越久。
零样本克隆：voice 传参考音频 URL，服务端用其音色合成 input 文本，无需预先创建角色。
ref_text 与计费：
- 提供 ref_text：直接用于克隆，积分按输入字数 ×1。
- 不提供 ref_text：自动调用一句话 ASR 识别参考音频得到 ref_text，积分按输入字数 ×3（含 ASR 成本）。ASR 识别失败时降级为无 ref_text 继续合成，仍按 ×3 计费。
配额退还：合成失败（synthesis_failed）自动退还已扣配额；转码失败（encode_failed）不退还（合成已成功）；ASR 失败降级不退还。
单次上限：受套餐 per_request_limit 约束（按输入字数，与倍率无关），超出返回 400 input_too_long。

2. 列出可用模型

GET /models

OpenAI 兼容端点。

响应示例

{
  "object": "list",
  "data": [
    {
      "id": "quips-tts-v1",
      "object": "model",
      "created": 1700000000,
      "owned_by": "quips"
    }
  ]
}

错误处理

所有错误返回 OpenAI 风格的 JSON 错误体：

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "voice"
  }
}

错误码一览

HTTP	type	code	触发场景
400	`invalid_request_error`	`model_not_found`	`model` 不支持
400	`invalid_request_error`	`unsupported_response_format`	`response_format` 不在支持列表
400	`invalid_request_error`	`invalid_speed`	`speed` 超出 0.25~4.0
400	`invalid_request_error`	`invalid_voice_url`	`voice` 非 http/https URL
400	`invalid_request_error`	`input_parse_failed`	`input` 为空
400	`invalid_request_error`	`input_too_long`	超出单次字数上限
401	`authentication_error`	`missing_api_key` / `invalid_api_key`	认证失败
403	`permission_error`	`subscription_required` / `api_access_denied`	权限不足
429	`rate_limit_error`	`daily_quota_exceeded`	超出当日配额
500	`server_error`	`synthesis_failed`	ASR/推理失败或空音频（已退款）
500	`server_error`	`encode_failed`	音频转码失败（不退款）

速率与配额

日配额：按套餐每日字符上限，文本字数累计扣减，UTC 次日零点重置。
计费倍率：提供 ref_text 时按字数 ×1；未提供（触发 ASR）时按字数 ×3。
单次上限：per_request_limit（与套餐挂钩，按字数校验，与倍率无关），超出返回 400 input_too_long。
配额退还：仅 synthesis_failed 退还；encode_failed 与 ASR 降级不退。

完整示例：Python 端到端

from openai import OpenAI

client = OpenAI(
    base_url="https://api2.lsmy.cc/api/v1",
    api_key="<your_api_key>",
)

# 确认模型
assert any(m.id == "quips-tts-v1" for m in client.models.list())

# 零样本克隆：voice 传参考音频 URL
text = "你好，这是开放 API 的零样本声音克隆测试。" * 10
response = client.audio.speech.create(
    model="quips-tts-v1",
    voice="https://cdn.example.com/your-ref-audio.wav",
    input=text,
    response_format="mp3",
    speed=1.0,
    extra_body={"ref_text": "参考音频对应的文本内容。"},  # 可选；不传则自动 ASR（积分 ×3）
)
response.write_to_file("output.mp3")
print("完成，音频字节数：", len(response.content))

常见问题

Q: voice 传什么？
A: 参考音频的公网 URL（https）。服务端用该音频的音色来合成你传入的 input 文本，实现零样本声音克隆。不再使用角色 ID。

Q: 要不要传 ref_text？
A: 可选。传了克隆质量更好且积分 ×1；不传则服务端自动 ASR 识别参考音频（积分 ×3）。若你知道参考音频说的话，建议传。

Q: 为什么返回的是音频而不是 JSON？
A: POST /audio/speech 是 OpenAI 兼容的同步接口，直接返回音频字节流。

Q: 支持流式输出吗？
A: 暂不支持流式。接口为同步全量返回，合成完成后一次性返回完整音频。

Q: 参考音频有什么要求？
A: 需为可公网访问的 https URL，服务端能直接拉取。建议清晰人声、10~30 秒、单一说话人，效果最佳。

灵声妙语

灵声妙语 API 开放文档

灵声妙语 开放 API 文档（公测，可能不稳定）

认证