PUREAM API

IndexTTS2 语音克隆

传入文本和音色参考音频，生成带情绪表达的 WAV 语音。100字符以内成功0.04元；超过100字符按全文3元/万字符计费，查询免费，失败不收费。

调用与计费

POST https://puream.cn/api/ai/indextts2/tasks
GET  https://puream.cn/api/ai/indextts2/tasks/{task_id}

Authorization: Bearer 你的纯梦APIKey或授权码
Content-Type: application/json
Idempotency-Key: 为本次生成准备的唯一字符串

1–100字符：0.04元/次。超过100字符：按本次全部输入字符数 × 3元 ÷ 10000计费。金额向上取整到分，标点、空格和换行也计数；按Unicode字符计数，不按字节、token或内部段数计费。101字符为0.04元，134字符为0.05元，1000字符为0.30元，5000字符为1.50元，10000字符为3元。

提交时预冻结本次计算出的金额，成功取得并校验音频后按提交时价格结算；已有任务不会因后续价格调整而重新计价。失败释放全部冻结金额；查询与相同幂等键的重复请求不重复扣费。不同参数必须使用不同幂等键；失败任务重做也需要新键。

提交返回 HTTP 202 和纯梦 task_id。每隔 3–5 秒查询同一个任务，直到 completed 或 failed；不要反复提交来获取进度。长文本各段按顺序合成，全部成功后合并为一个 WAV。整次输入只计算一次费用，内部拆段不重复计费；任一段失败则整次不收费，不返回不完整音频。

segments_total 和 segments_completed 表示总段数与已完成段数；phase 为 queued、running、merging 或 completed。合并后从 results[0].url 或 result_url 下载，并在 expires_at 前保存到自己的设备或存储。

data.text_characters 是本次输入字符数；data.quoted_charge_cents 和 data.quoted_charge_yuan 是提交时确定的费用，单位分别为分和元。失败后仍可查看原报价，实际收费以 billing_status 和 charge_cents 为准。

参考音频与文本限制

文本：1–50000 个字符，自动分批合成。上游每次最多2048个字符。超过时，从2048字符范围内最后一个标点之后分段，保留标点与原文顺序；范围内没有标点时才按字符上限切分，不会丢字。纯梦按 Unicode 字符计数，标点、空格也计数，不等同于 token。

例如5000字符会拆为多段，每段最多2048字符；具体段数取决于标点位置。音色、情绪参数在各段保持一致，合并时统一采样率与声道。长文需要更久，请持续查询原 task_id。

参考音频：MP3 或 WAV。上游没有公开音频秒数的硬限制。IndexTTS2 官方模型代码会截取音色参考、情绪参考的前 15 秒；本服务建议使用 5–15 秒清晰、连续、单人干声，开头避免长静音和背景音乐。这是使用建议，不是上游公布的秒数拒绝规则。

base64 可使用原始编码或带 audio/mpeg、audio/wav 类型的 data URL；纯梦对每个 base64 音频设 20 MiB 上限。使用 URL 时须为公网可访问直链，不能传入 Markdown 链接语法。

情绪向量仅在“使用情感向量控制”时生效；“与音色参考音频相同”会跟随音色音频的情绪，即使填写 emo_happy 和 emo_calm 也不会切换为向量模式。本工作流未开放自然语言情绪描述字段。

请求字段

字段	类型	必填	说明
`prompt_text`	string	是	要朗读的合成文本，1–50000 个字符；标点、空格也计数。超过2048字符自动按标点分段并合并。
`prompt_simple`	string	是	音色参考音频：公网 MP3/WAV URL 或 base64 文件。字段名按上游保留。
`emo_control_method`	string	是	与音色参考音频相同 / 使用情感参考音频 / 使用情感向量控制
`emo_ref_audio`	string	条件必填	情绪参考音频，MP3/WAV URL 或 base64；仅“使用情感参考音频”模式生效。
`emo_random`	boolean	否	是否随机采样情绪风格，默认 false；它不是语音生成的随机种子。
`emo_happy`	number	否	高兴，0–1.4，默认 0。
`emo_angry`	number	否	愤怒，0–1.4，默认 0。
`emo_sad`	number	否	悲伤，0–1.4，默认 0。
`emo_afraid`	number	否	恐惧，0–1.4，默认 0。
`emo_disgusted`	number	否	厌恶，0–1.4，默认 0。
`emo_melancholic`	number	否	低落，0–1.4，默认 0。
`emo_calm`	number	否	平静，0–1.4，默认 0。
`emo_surprised`	0 或 "0"	否	惊讶：本工作流目前只开放枚举 0；其余数值会被拒绝。
`idempotency_key`	string	否	也可放入 Idempotency-Key 请求头，最多 200 字符。同一账号与键只创建一个任务。
`authorization_code / api_key`	string	否	仅提交时的鉴权兼容字段；推荐提交和查询均用 Authorization: Bearer。

提交示例

把示例地址替换为真实人声参考文件。下面的情绪配置在“使用情感向量控制”模式下生效。

{
  "prompt_text": "你好，这是一段测试文本",
  "prompt_simple": "https://example.com/voice.wav",
  "emo_control_method": "使用情感向量控制",
  "emo_happy": 0.5,
  "emo_calm": 0.3,
  "emo_random": false
}

成功结果

{
  "code": "Success",
  "msg": "",
  "data": {
    "task_id": "itts2_...",
    "status": "completed",
    "result_url": "https://example.com/result.wav",
    "results": [
      {
        "url": "https://example.com/result.wav",
        "type": "audio",
        "file_type": "wav",
        "output_type": "output"
      }
    ],
    "duration_seconds": 3.2,
    "reused": false
  },
  "charge_cents": 4,
  "charge_yuan": 0.04,
  "billing_status": "charged"
}

上述短文本示例成功收费0.04元。处理中 billing_status 为 pending，charge_cents 与 charge_yuan 为 null；失败为 not_charged、金额0。结算使用已预冻结的本次报价，不会额外再扣一次。

音频保留24小时

新生成的音频仅存入阿里云 OSS 私有临时目录，官网不永久保存音频，数据库不保存合成文件或下载链接，仅保留任务、计费及校验元数据。合并时使用的服务器临时文件会在处理结束后删除。

下载链接在音频完成后24小时固定失效，重复查询不会延长。系统每分钟检查到期文件并删除，OSS 的1天生命周期规则作为兜底；云服务故障可能延迟物理删除，但不会延长下载权限。过期查询返回 status: expired、error_code: RESULT_EXPIRED、空 results 和 result_url: null；原成功账单保留，使用新幂等键可重新生成。

异常处理

400：修正字段；401：检查纯梦密钥；402：余额不足；409：幂等键与参数冲突；413：base64 或请求体过大。查询遇到短暂上游或存储故障时保留原任务继续查询；24 小时仍未取得可交付音频会失败并释放预冻结。

提交响应丢失时用同一幂等键重试。若返回 failed 与 UPSTREAM_SUBMIT_UNCONFIRMED，表示某一段上游是否收单无法确认，纯梦本次不收费，也不会自动重复提交。暂时的查询或存储故障会保留已完成分段并恢复，不重新合成成功的段。

参数核验日期：2026-09-08。依据：工作流调用表单、异步接口说明、官方音频截取实现。