> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soulx.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 接口概览

> SoulX API 接口能力、模型、错误码与价格概览

export const PriceCalculator = () => {
  const tiers = [{
    id: "100k",
    label: "10 万字符",
    characters: 100000,
    price: 34,
    unitPrice: "¥3.4 / 万字符",
    validity: "1 个月"
  }, {
    id: "2m",
    label: "200 万字符",
    characters: 2000000,
    price: 610,
    unitPrice: "¥3.05 / 万字符",
    validity: "3 个月"
  }, {
    id: "20m",
    label: "2,000 万字符",
    characters: 20000000,
    price: 5800,
    unitPrice: "¥2.9 / 万字符",
    validity: "1 年"
  }, {
    id: "200m",
    label: "20,000 万字符",
    characters: 200000000,
    price: 54000,
    unitPrice: "¥2.7 / 万字符",
    validity: "1 年"
  }];
  const formatCurrency = value => new Intl.NumberFormat("zh-CN", {
    style: "currency",
    currency: "CNY",
    maximumFractionDigits: 0
  }).format(value);
  const formatNumber = value => new Intl.NumberFormat("zh-CN").format(value);
  const [selectedTierId, setSelectedTierId] = useState(tiers[0].id);
  const [quantityInput, setQuantityInput] = useState("1");
  const selectedTier = tiers.find(tier => tier.id === selectedTierId) ?? tiers[0];
  const quantity = Math.max(1, Number.parseInt(quantityInput, 10) || 1);
  const estimatedPrice = selectedTier.price * quantity;
  const estimatedCharacters = selectedTier.characters * quantity;
  const adjustQuantity = step => {
    setQuantityInput(String(Math.max(1, quantity + step)));
  };
  return <section className="not-prose mt-10 overflow-hidden rounded-lg border border-zinc-200 bg-white shadow-sm dark:border-zinc-800 dark:bg-zinc-950">
      <div className="border-b border-zinc-200 px-5 py-4 dark:border-zinc-800">
        <h2 className="text-lg font-semibold text-zinc-950 dark:text-white">价格预估</h2>
        <p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">
          选择字符数档位并填写购买数量，预估费用将自动计算。
        </p>
      </div>

      <div className="space-y-7 px-5 py-5">
        <div>
          <div className="mb-3 text-sm font-medium text-zinc-800 dark:text-zinc-200">
            字符数档位
          </div>
          <div className="grid gap-3 md:grid-cols-2 xl:grid-cols-4">
            {tiers.map(tier => {
    const isSelected = tier.id === selectedTier.id;
    return <button key={tier.id} type="button" onClick={() => setSelectedTierId(tier.id)} className={["rounded-lg border px-4 py-3 text-left transition", isSelected ? "border-blue-500 bg-blue-50 text-blue-700 dark:border-blue-400 dark:bg-blue-950/50 dark:text-blue-200" : "border-zinc-200 bg-white text-zinc-800 hover:border-blue-300 hover:bg-blue-50/60 dark:border-zinc-800 dark:bg-zinc-950 dark:text-zinc-200 dark:hover:border-blue-700 dark:hover:bg-blue-950/30"].join(" ")} aria-pressed={isSelected}>
                  <span className="block min-h-6 text-base font-semibold leading-6">
                    {tier.label}
                  </span>
                  <span className="mt-3 block text-sm font-medium leading-5 opacity-90">
                    {formatCurrency(tier.price)}
                  </span>
                  <span className="mt-1 block min-h-5 text-sm leading-5 opacity-80">
                    {tier.unitPrice}
                  </span>
                  <span className="mt-3 block text-sm leading-5 opacity-70">
                    有效期：{tier.validity}
                  </span>
                </button>;
  })}
          </div>
        </div>

        <div>
          <label htmlFor="price-calculator-quantity" className="mb-3 block text-sm font-medium text-zinc-800 dark:text-zinc-200">
            购买数量
          </label>
          <div className="flex w-full max-w-xs overflow-hidden rounded-lg border border-zinc-200 dark:border-zinc-800">
            <button type="button" onClick={() => adjustQuantity(-1)} className="h-11 w-12 border-r border-zinc-200 text-lg font-semibold text-zinc-500 hover:bg-zinc-50 dark:border-zinc-800 dark:text-zinc-300 dark:hover:bg-zinc-900" aria-label="减少购买数量">
              -
            </button>
            <input id="price-calculator-quantity" type="number" min="1" step="1" value={quantityInput} onChange={event => setQuantityInput(event.target.value)} onBlur={() => setQuantityInput(String(quantity))} className="h-11 min-w-0 flex-1 border-0 bg-white px-3 text-center text-sm font-medium text-zinc-950 outline-none focus:ring-2 focus:ring-blue-500 dark:bg-zinc-950 dark:text-white" />
            <button type="button" onClick={() => adjustQuantity(1)} className="h-11 w-12 border-l border-zinc-200 text-lg font-semibold text-zinc-500 hover:bg-zinc-50 dark:border-zinc-800 dark:text-zinc-300 dark:hover:bg-zinc-900" aria-label="增加购买数量">
              +
            </button>
          </div>
        </div>
      </div>

      <div className="flex flex-col gap-2 border-t border-zinc-200 bg-zinc-50 px-5 py-4 dark:border-zinc-800 dark:bg-zinc-900/50 sm:flex-row sm:items-end sm:justify-between">
        <div>
          <div className="text-sm text-zinc-600 dark:text-zinc-400">预估费用</div>
          <div className="mt-1 text-3xl font-semibold text-orange-500">
            {formatCurrency(estimatedPrice)}
          </div>
        </div>
        <div className="text-sm text-zinc-600 dark:text-zinc-400">
          {formatNumber(estimatedCharacters)} 字符，有效期 {selectedTier.validity}
        </div>
      </div>
    </section>;
};

本文档涵盖以下内容：

* **模型列表**：当前开放的模型清单，包括播客模型、对话模型。
* **接口简介**：各能力的功能描述、特性与下属接口；接口包含音色管理、音色复刻、对话语音合成、播客语音合成等能力。
* **错误码查询**：所有接口共享的状态码及含义、推荐处理方式。
* **API 刊例价格**：合成类接口（对话语音合成、播客语音合成）的原价与套餐折扣信息。

## 获取 API Key

通过 **账户 -> 接口密钥 -> 创建新的 API Key** 获取 API Key。

## 模型列表

| 类型   | 模型列表                    |
| ---- | ----------------------- |
| 播客模型 | `soulx-tts-podcast-1.0` |
| 对话模型 | `soulx-tts-chat-1.0`    |

## 接口简介

### 音色管理

音色管理用于查询、维护当前账号下可用的音色资源（系统音色 + 复刻/克隆音色）。该能力支持以下功能：

* 同时查询系统音色与复刻音色，便于业务方选择合适的音色；
* 支持按音色类型筛选（仅系统、仅复刻、全部）；
* 支持删除指定的复刻/克隆音色（系统音色不支持删除）。

#### 接口说明

音色管理共包含 2 个接口，可按需选择使用。

* 查询音色列表
* 删除音色

### 音色复刻

音色复刻用于基于用户提供的一段参考音频快速复刻出新的自定义音色，并支持复刻后立即试听。该能力支持以下功能：

* 支持基于上传音频（mp3 / wav / m4a）进行声音克隆；
* 支持复刻后立即合成一段试听音频，验证音色效果；
* 支持降噪、去混响、音量归一化等音频前处理开关；
* 支持自定义 `voice_id` 命名（同账号下唯一）。

#### 支持模型

| 模型 ID                   | 用途         |
| ----------------------- | ---------- |
| `soulx-tts-podcast-1.0` | 复刻后用播客模型试听 |
| `soulx-tts-chat-1.0`    | 复刻后用对话模型试听 |

#### 接口说明

音色复刻共包含 1 个接口。

* 音色复刻

### 对话式语音合成

对话语音合成用于对话场景的语音合成，单次可处理最长 **10,000 字符** 的文本，如果字数大于 **3,000 字**，推荐使用流式输出。该能力支持以下功能：

* 支持系统音色、复刻音色自主选择；
* 支持多种音频规格、格式，覆盖 pcm / mp3 / m4a / wav；
* 支持流式输出（流式仅支持 base64）；
* 支持上文 `previous_context` 注入，让模型更贴合对话语境；
* 支持字符级字幕（`enable_subtitle`，仅非流式）。

#### 支持模型

| 模型 ID                | 说明       |
| -------------------- | -------- |
| `soulx-tts-chat-1.0` | 对话语音合成模型 |

#### 接口说明

对话语音合成功能共包含 1 个接口。

* HTTP 同步语音合成

#### 支持语言

* 中文
* 英文

### 播客语音合成

同步播客语音合成用于播客场景的语音合成，单次可处理最长 **10,000 字符** 的文本。该能力支持以下功能：

* 支持多说话人台本（`[speaker0]...[speaker1]...`），每个说话人独立配置音色；
* 支持系统音色、复刻音色自主选择；
* 支持多种音频规格、格式，覆盖 pcm / mp3 / m4a / wav；
* 支持句级别流式输出（流式尾包可附带整段完整音频与时长，`enable_complete_data=true`）；
* 支持字幕（仅流式）。

#### 支持模型

| 模型 ID                   | 说明       |
| ----------------------- | -------- |
| `soulx-tts-podcast-1.0` | 播客语音合成模型 |

#### 接口说明

播客语音合成功能共包含 1 个接口。

* HTTP 同步播客语音合成

#### 支持语言

* 中文
* 英文

## 错误码查询

所有接口共享同一套 `base_resp.status_code` 错误码：

| 错误码  | 含义       | 解决方案          |
| ---- | -------- | ------------- |
| 1000 | 未知错误     | 稍后重试          |
| 1001 | 超时       | 稍后重试 / 设长超时时间 |
| 1002 | 触发限流     | 联系我们          |
| 1004 | 鉴权失败     | 检查 API Key    |
| 1013 | 服务内部错误   | 稍后重试          |
| 1041 | 审核未通过    | 调整输入内容        |
| 1051 | 积分不足     | 检查账户余额        |
| 1052 | 复刻音色已达上限 | 检查音色数量        |
| 2013 | 输入参数错误   | 检查请求参数        |
| 2038 | 无复刻权限    | 请检查账号认证状态     |

## API 接口价格

针对合成接口：**对话式语音合成**、**播客语音合成**。

原价：**¥3.4 / 万字符**

| 分类     | 套餐一<br />（节省约 10%） | 套餐二<br />（节省约 15%） | 套餐三<br />（节省约 20%） |
| ------ | :----------------: | :----------------: | :----------------: |
| 折扣价    |        ¥610        |       ¥5,800       |       ¥54,000      |
| 原价     |        ¥680        |       ¥6,800       |       ¥68,000      |
| 有效期    |        3 个月        |         1 年        |         1 年        |
| 总字符数   |    2,000,000 字符    |    20,000,000 字符   |   200,000,000 字符   |
| 单价/万字符 |        ¥3.05       |        ¥2.9        |        ¥2.7        |

<Note>
  如果订阅量超出上述套餐范围，可联系官方进行商务定制。
  <br />套餐权益、适用接口范围、并发能力、额度消耗规则和超额计费说明请联系官方沟通详情。
</Note>

<PriceCalculator />