---
name: cinqak-tts
description: 通过 Cinqak OpenAI 兼容接口进行维吾尔语 / 中文语音合成（TTS）。当用户需要文字转语音、批量配音、把脚本/文章转成音频、或查询可用音色与账户额度时使用。
---

# Cinqak TTS Skill

通过 Cinqak 的 OpenAI 兼容语音合成 API，把文本合成为维吾尔语或中文音频。
接口与 your 网页账户共用同一份字符额度（1 积分 = 1 字符）。

## 何时使用

- 用户要求"把这段文字读出来 / 生成语音 / 配音 / 转音频"
- 用户需要维吾尔语（Uyghur）或中文 TTS
- 用户想批量把多段文本转成语音文件
- 用户想查询可用音色、当前额度或用量明细

## 前置条件

- 一个 Cinqak API Key（`sk-` 开头），在 https://cinqak.cn/keys 创建（明文仅显示一次）。
- Base URL：`https://cinqak.cn/v1`
- 鉴权：`Authorization: Bearer <你的 sk- 密钥>`

## 接口

### 1. 文本转语音 · `POST /v1/audio/speech`

请求体（JSON）：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 固定 `yixotts` |
| `input` | string | 是 | 待合成文本（维/中），最长 800 字符 |
| `voice` | string | 是 | 音色 ID，见下方 `/v1/voices` |
| `accent` | string | 否 | 重音 / 风格参数 |
| `response_format` | string | 否 | `wav`（默认）或 `mp3` |

成功返回音频二进制（Content-Type 为 audio/wav 或 audio/mpeg）。

cURL 示例：

```bash
curl https://cinqak.cn/v1/audio/speech \
  -H "Authorization: Bearer $CINQAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yixotts",
    "input": "سىنچاققا خۇش كەلدىڭىز",
    "voice": "ug-female-01",
    "response_format": "wav"
  }' \
  --output result.wav
```

Python（openai SDK）示例：

```python
from openai import OpenAI

client = OpenAI(api_key="sk-你的密钥", base_url="https://cinqak.cn/v1")

response = client.audio.speech.create(
    model="yixotts",
    input="سىنچاققا خۇش كەلدىڭىز",
    voice="ug-female-01",
)
response.stream_to_file("result.wav")
```

Node.js（openai SDK）示例：

```javascript
import OpenAI from "openai";
import { writeFileSync } from "node:fs";

const client = new OpenAI({ apiKey: "sk-你的密钥", baseURL: "https://cinqak.cn/v1" });

const res = await client.audio.speech.create({
  model: "yixotts",
  input: "سىنچاققا خۇش كەلدىڭىڭىز",
  voice: "ug-female-01",
});
writeFileSync("result.wav", Buffer.from(await res.arrayBuffer()));
```

### 2. 列出音色 · `GET /v1/voices`

```bash
curl https://cinqak.cn/v1/voices -H "Authorization: Bearer $CINQAK_API_KEY"
```

返回 `{ "object": "list", "default": "...", "data": [ { "id", "name", "language" }, ... ] }`。

### 3. 查询额度 · `GET /v1/usage`

```bash
curl https://cinqak.cn/v1/usage -H "Authorization: Bearer $CINQAK_API_KEY"
```

返回 `quota`、`used_chars`、`request_count`、`daily`（近 30 天）。

### 4. 用量明细 · `GET /v1/usage/records`

分页：`limit`（≤500，默认 50）、`before`（上一页返回的 `next_before` 游标）。

```bash
curl "https://cinqak.cn/v1/usage/records?limit=20" -H "Authorization: Bearer $CINQAK_API_KEY"
```

## 错误处理

- 鉴权失败：`401`，`{ "error": "unauthorized" }`
- 额度不足：接口返回相应错误，请提示用户去 https://cinqak.cn 充值
- 参数错误：`400`
- 速率限制：`429`

## 使用流程（建议）

1. 若用户未提供音色，先调用 `GET /v1/voices` 取可用音色并询问偏好（或默认用 `default`）。
2. 调用 `POST /v1/audio/speech` 合成，保存为文件。
3. 若需多段，逐段合成；每段消耗字符数 = 文本长度，从用户额度扣除。
4. 合成失败时检查错误体，额度不足时引导用户充值。

## 安全提示

- API Key 等同于账户凭证，不要写入客户端代码或提交到仓库。
- 优先从环境变量（如 `CINQAK_API_KEY`）读取。