PixMind Docs
API 接入指南

文字转语音 API

查询音色、合成语音，并通过 PixMind API 获取音频结果。

将文稿合成为可下载的音频。先从已配置供应商的目录选择音色，再发起同步合成请求。

操作方法请求端点
查询音色GET/api-platform/v1/tts/voices
合成语音POST/api-platform/v1/tts/synthesize

打开 TTS 调试器 · 创建 API Key

鉴权

服务地址：https://aihub-admin.aimix.pro

使用已启用且有音频权限的 PixMind API Key，通过 Authorization 请求头传入。POST 请求还需设置 Content-Type: application/json。

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

快速开始

以下示例使用微软线路和中文音色。合成接口直接返回音频链接，无需轮询任务。

生成一段配音
curl 'https://aihub-admin.aimix.pro/api-platform/v1/tts/synthesize' \
  -H "Authorization: Bearer $PIXMIND_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: narration-order-001' \
  -d '{
    "provider": "microsoft-api",
    "voiceId": "zh-CN-XiaoxiaoNeural",
    "text": "欢迎使用 PixMind。",
    "format": "mp3"
  }'

响应示例。下面的 URL 仅用于展示结构，实际使用响应中的 audioUrl。

200 · 语音合成结果
{
  "code": 1000,
  "data": {
    "audioUrl": "https://example.com/narration.mp3",
    "format": "mp3",
    "provider": "microsoft-api",
    "model": "tts:microsoft-api",
    "type": "tts",
    "usage": {
      "characters": 13,
      "units": 1,
      "credits": 0
    }
  }
}

查询音色

GET /api-platform/v1/tts/voices

查询参数

参数类型必填默认值说明
providerstring否all下方表格中的供应商 ID，或 all。仅返回已配置的供应商。
languagestring否all微软语言代码，如 zh-CN、en-US；最多 40 字符。其余供应商返回完整分组。
查询微软中文音色
curl 'https://aihub-admin.aimix.pro/api-platform/v1/tts/voices?provider=microsoft-api&language=zh-CN' \
  -H "Authorization: Bearer $PIXMIND_API_KEY"

音色目录响应

目录按供应商和语言分组。选择的音色需与合成请求中的供应商一致。

供应商voiceId 的读取位置
微软grouped[language][].id，或 list[].key
火山grouped.all[].id，或 list[].key
Googlegrouped.all[].key；list 是按模型分组、包含音色数组的对象
MiniMax / 讯捷国语grouped.all[].key，或 list[].key
响应结构 · 已缩短的示例
{
  "code": 1000,
  "data": {
    "microsoft-api": {
      "grouped": {
        "zh-CN": [
          {
            "id": "zh-CN-XiaoxiaoNeural",
            "name": "晓晓",
            "gender": "Female",
            "lang": "中文(普通话，简体)",
            "type": "microsoft-api"
          }
        ]
      },
      "list": [
        {
          "key": "zh-CN-XiaoxiaoNeural",
          "name": "晓晓",
          "type": "microsoft-api"
        }
      ]
    }
  }
}

目录可能提供用于试听的 example_voice_url，并保留各供应商的专属信息。明确查询一个未配置的供应商时返回 503。

合成语音

POST /api-platform/v1/tts/synthesize

请求体参数

参数类型必填默认值说明
textstring是—非空白文稿，长度 1–10,000 个 JavaScript UTF-16 代码单元；空白字符计入长度。
voiceIdstring是—所选供应商目录中的音色 ID，最多 200 字符。
providerstring否microsoft-api精确供应商 ID，区分大小写；见下方供应商配置表。
formatstring否供应商默认值该供应商支持的音频格式。
speednumber否供应商默认值语速，各供应商范围不同。
pitchnumber否0音调调整；Google、火山及讯捷国语只接受 0。
volumenumber否供应商默认值供应商支持范围内的音量。
stylePromptstring否—仅 Google 支持，最多 2,000 字符。
emotionstring否—仅 MiniMax 支持，最多 2,000 字符。
modelstring否供应商默认模型仅 Google、MiniMax 支持；使用当前供应商支持的模型，最多 2,000 字符。

接口拒绝未知字段。不要传入应用 ID、租户 ID、计费字段或网站内部上下文。

供应商配置

供应商 ID支持格式默认格式语速范围 / 默认值音量范围 / 默认值音调范围 / 默认值
microsoft-apimp3mp3−100 至 100 / 00 至 100 / 100−100 至 100 / 0
google-genaimp3、wav、oggmp30 至 2 / 11 至 2 / 1仅 0
huoshan_big_modelmp3、wavmp30.8 至 2 / 10.5 至 2 / 1仅 0
MiniMaxmp3mp30.5 至 2 / 10 至 10 / 1−12 至 12 / 0
xjguoyuwavwav0 至 2 / 11 至 2 / 1仅 0

省略可选参数时使用该供应商的默认值。一个供应商可用的数值，不一定适用于另一个供应商。

响应字段

data 内字段类型说明
audioUrlstring合成音频的地址。
formatstring实际返回的音频格式。
providerstring所选供应商 ID。
modelstring用量日志标识，如 tts:microsoft-api；不同于请求体中可选的 model。
typestring固定为 tts。
durationnumber，可选仅当合成服务提供时长时返回。
usage.charactersnumber按 JavaScript UTF-16 代码单元计算的输入长度。
usage.unitsnumber输入长度除以 100，向上取整。
usage.creditsnumber请求实际收取的 API 积分。

SDK 示例

TypeScript

在服务端设置 PIXMIND_API_KEY 后运行。每段计划生成的配音只创建一个幂等键，相同请求重试时复用该键。

Node.js · 合成配音
import { randomUUID } from "node:crypto";

const requestId = randomUUID();
const response = await fetch(
  "https://aihub-admin.aimix.pro/api-platform/v1/tts/synthesize",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PIXMIND_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": requestId,
    },
    body: JSON.stringify({
      provider: "microsoft-api",
      voiceId: "zh-CN-XiaoxiaoNeural",
      text: "欢迎使用 PixMind。",
      format: "mp3",
    }),
    signal: AbortSignal.timeout(120_000),
  },
);

const result = await response.json();
if (!response.ok || result.code !== 1000) {
  throw new Error(result.message ?? `HTTP ${response.status}`);
}

console.log(result.data.audioUrl);
console.log(result.data.usage);

Python

Python · 合成配音
import os
import uuid
import requests

request_id = str(uuid.uuid4())
response = requests.post(
    "https://aihub-admin.aimix.pro/api-platform/v1/tts/synthesize",
    headers={
        "Authorization": "Bearer " + os.environ["PIXMIND_API_KEY"],
        "Idempotency-Key": request_id,
    },
    json={
        "provider": "microsoft-api",
        "voiceId": "zh-CN-XiaoxiaoNeural",
        "text": "欢迎使用 PixMind。",
        "format": "mp3",
    },
    timeout=120,
)

result = response.json()
if not response.ok or result.get("code") != 1000:
    raise RuntimeError(result.get("message", "语音合成失败"))

print(result["data"]["audioUrl"])
print(result["data"]["usage"])

计费与可用性

付费供应商按每 100 字符向上取整：Math.ceil(text.length / 100)。JavaScript text.length 按 UTF-16 代码单元计算，因此部分表情符号的长度为 2。微软线路当前不收 API 积分。

使用同一 API Key 查询 GET /api-platform/v1/tools，读取 prices 和 ttsAvailability。付费价格项为 GoogleTTS、HuoshanTTS、MiniMaxTTS、XjguoyuTTS。请求使用 API 钱包计费，不受网站免费套餐单次 100 字符上限影响。

合成或音频上传失败会按原收费流水退款。客户端超时不能说明服务端是否已完成，请保留原幂等键。

幂等与重试

Idempotency-Key 可选，建议合成时使用。接受 1–128 个可打印 ASCII 字符，在同一 API 应用和操作范围内保留 24 小时。

情况行为
相同键、相同归一化请求，原请求已完成返回缓存的合成结果。
相同键，但请求内容改变返回 409。
原请求处理中或结果不确定返回 409，不另建一次合成请求。

超时或冲突后，不要自动更换新键再次提交。

错误处理

错误包含 HTTP 状态和 JSON 响应体。调用方同时检查 response.ok 与 code。

示例 · 输入不合法
{
  "code": 400,
  "message": "text must contain 1 to 10000 characters.",
  "data": null
}
HTTP 状态常见原因处理方式
400空白文字、未知字段、音色或供应商参数不合法、格式或数值越界按参数表修正请求。
401API Key 缺失、无效或已禁用检查 Bearer Key 和启用状态。
403API Key 没有音频权限为此 Key 启用音频权限。
409幂等冲突，或原请求处理中、结果不确定保留原请求标识，避免重复提交。
429超过请求频率或并发限制按对应限制处理，不另建重复请求。
503语音供应商未配置选择工具目录中标为可用的供应商。
5xx合成或结果交付失败重试前查看公开错误信息和 API 用量日志。

相关接口

视频转分镜提示词

从视频提取分镜描述和生成提示词。

错误码与重试

处理标准化 API 错误并安全重试。

On this page

鉴权快速开始查询音色查询参数音色目录响应合成语音请求体参数供应商配置响应字段SDK 示例TypeScriptPython计费与可用性幂等与重试错误处理相关接口