Text to Speech API

Convert a script into downloadable audio. Choose a voice from the configured provider catalogue, then submit a synchronous synthesis request.

Operation	Method	Endpoint
List voices	`GET`	`/api-platform/v1/tts/voices`
Synthesize speech	`POST`	`/api-platform/v1/tts/synthesize`

Open TTS Playground · Create an API key

Authentication

Base URL: https://aihub-admin.aimix.pro

Use an enabled PixMind API key with audio permission. Send the key in the Authorization header. POST requests also require Content-Type: application/json.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Quickstart

The following request uses the Microsoft route and an English voice. Synthesis returns the audio URL directly; there is no task polling step.

Create a narration

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": "en-US-AriaNeural",
    "text": "Welcome to PixMind.",
    "format": "mp3"
  }'

Example response. The URL is illustrative; use the actual returned audioUrl.

200 · Speech synthesis result

{
  "code": 1000,
  "data": {
    "audioUrl": "https://example.com/narration.mp3",
    "format": "mp3",
    "provider": "microsoft-api",
    "model": "tts:microsoft-api",
    "type": "tts",
    "usage": {
      "characters": 19,
      "units": 1,
      "credits": 0
    }
  }
}

List voices

GET /api-platform/v1/tts/voices

Query parameters

Parameter	Type	Required	Default	Description
`provider`	string	No	`all`	A provider ID from the table below, or `all`. Only configured providers are returned.
`language`	string	No	`all`	Microsoft language code, such as `en-US` or `zh-CN`; maximum 40 characters. Other providers return their full group.

Find an English Microsoft voice

curl 'https://aihub-admin.aimix.pro/api-platform/v1/tts/voices?provider=microsoft-api&language=en-US' \
  -H "Authorization: Bearer $PIXMIND_API_KEY"

Voice catalogue response

The response groups voices by provider and language. Select the voice from the same provider you use for synthesis.

Provider	Where to read `voiceId`
Microsoft	`grouped[language][].id`, or `list[].key`
Huoshan	`grouped.all[].id`, or `list[].key`
Google	`grouped.all[].key`; `list` is an object containing arrays grouped by model
MiniMax / Xjguoyu	`grouped.all[].key`, or `list[].key`

Response structure · shortened example

{
  "code": 1000,
  "data": {
    "microsoft-api": {
      "grouped": {
        "en-US": [
          {
            "id": "en-US-AriaNeural",
            "name": "Aria",
            "gender": "Female",
            "lang": "英语(美国)",
            "en_lang": "English (American)",
            "type": "microsoft-api"
          }
        ]
      },
      "list": [
        {
          "key": "en-US-AriaNeural",
          "name": "Aria",
          "type": "microsoft-api"
        }
      ]
    }
  }
}

Catalogue entries may include example_voice_url for auditioning. Provider-specific metadata is preserved. An explicitly requested, unconfigured provider returns 503.

Synthesize speech

POST /api-platform/v1/tts/synthesize

Request body

Parameter	Type	Required	Default	Description
`text`	string	Yes	—	Non-blank script, 1–10,000 JavaScript UTF-16 code units. Whitespace counts toward length.
`voiceId`	string	Yes	—	Voice ID from the selected provider's catalogue; maximum 200 characters.
`provider`	string	No	`microsoft-api`	Exact provider ID, including case. See provider settings below.
`format`	string	No	Provider default	Audio format accepted by that provider.
`speed`	number	No	Provider default	Speech speed. Ranges differ by provider.
`pitch`	number	No	`0`	Pitch adjustment. Google, Huoshan and Xjguoyu only accept `0`.
`volume`	number	No	Provider default	Volume within the provider's supported range.
`stylePrompt`	string	No	—	Google only; maximum 2,000 characters.
`emotion`	string	No	—	MiniMax only; maximum 2,000 characters.
`model`	string	No	Provider default	Google or MiniMax only; use a model supported by the configured provider. Maximum 2,000 characters.

Unknown request fields are rejected. Do not send app IDs, tenant IDs, billing fields or the website's internal context.

Provider settings

Provider ID	Formats	Default format	Speed range / default	Volume range / default	Pitch range / default
`microsoft-api`	`mp3`	`mp3`	−100 to 100 / `0`	0 to 100 / `100`	−100 to 100 / `0`
`google-genai`	`mp3`, `wav`, `ogg`	`mp3`	0 to 2 / `1`	1 to 2 / `1`	`0` only
`huoshan_big_model`	`mp3`, `wav`	`mp3`	0.8 to 2 / `1`	0.5 to 2 / `1`	`0` only
`MiniMax`	`mp3`	`mp3`	0.5 to 2 / `1`	0 to 10 / `1`	−12 to 12 / `0`
`xjguoyu`	`wav`	`wav`	0 to 2 / `1`	1 to 2 / `1`	`0` only

Omit optional controls to use that provider's defaults. A numeric value valid for one provider may be invalid for another.

Response fields

Field inside `data`	Type	Description
`audioUrl`	string	URL of the synthesized audio.
`format`	string	Actual returned audio format.
`provider`	string	Selected provider ID.
`model`	string	Usage-log identifier, such as `tts:microsoft-api`. This is not the optional request `model`.
`type`	string	Always `tts`.
`duration`	number, optional	Included only when the synthesis service provides duration.
`usage.characters`	number	Input length measured as JavaScript UTF-16 code units.
`usage.units`	number	Character count divided by 100, rounded up.
`usage.credits`	number	Actual API credits charged for the request.

SDK examples

TypeScript

Run this on your server with PIXMIND_API_KEY set. Generate one idempotency key for each intended narration and reuse it for any identical retry.

Node.js · synthesize narration

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: "en-US-AriaNeural",
      text: "Welcome to 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 · synthesize narration

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": "en-US-AriaNeural",
        "text": "Welcome to PixMind.",
        "format": "mp3",
    },
    timeout=120,
)

result = response.json()
if not response.ok or result.get("code") != 1000:
    raise RuntimeError(result.get("message", "Speech synthesis failed"))

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

Paid providers bill in 100-character units, rounded up: Math.ceil(text.length / 100). JavaScript text.length counts UTF-16 code units, so some emoji count as two units of length. Microsoft currently charges zero API credits.

Query GET /api-platform/v1/tools with the same API key to read prices and ttsAvailability. Paid pricing uses GoogleTTS, HuoshanTTS, MiniMaxTTS and XjguoyuTTS. API usage is billed through the API wallet. The website's free-plan 100-character limit does not apply to this endpoint.

Synthesis or audio-output upload failure refunds the original charge. A timeout in your client does not establish whether the server finished; keep the original idempotency key.

Idempotency and retries

Idempotency-Key is optional, but recommended for synthesis. It accepts 1–128 printable ASCII characters and is retained for 24 hours within the API application and operation.

Situation	Behaviour
Same key, same normalized request, completed	Returns the cached result.
Same key, changed request	Returns `409`.
Original request processing or result uncertain	Returns `409`; does not start another synthesis.

Do not automatically generate a new key after a timeout or conflict.

Errors

Errors use HTTP status plus a JSON envelope. Inspect both response.ok and code.

Example · invalid input

{
  "code": 400,
  "message": "text must contain 1 to 10000 characters.",
  "data": null
}

HTTP status	Common cause	Next step
`400`	Empty text, unknown field, wrong voice/provider parameter, unsupported format or numeric range	Correct the request using the parameter tables.
`401`	Missing, invalid or disabled API key	Check the Bearer key and its status.
`403`	The key does not allow audio access	Enable audio permission for this API key.
`409`	Idempotency conflict or processing/uncertain original request	Keep the original request ID; avoid a duplicate submission.
`429`	API rate limit or concurrency limit	Respect the applicable limit; do not submit a new duplicate request.
`503`	Requested speech provider is not configured	Select a provider marked available by the tools catalogue.
`5xx`	Synthesis or output delivery failure	Inspect the public message and API usage log before retrying.