Text-to-Speech API Docs

Overview

Your instance's Base URL is the same link you use to open the app itself — it's a real backend (devnen/Chatterbox-TTS-Server) with a real HTTP API underneath, sitting behind a password gate.

Base URL	https://your-instance.app.cloudpc.live
Auth	Session cookie (`cpc_gate`) — see Authentication
Speech format	OpenAI-compatible — `POST /v1/audio/speech`
Response	Raw audio bytes (`wav`, `opus`, or `mp3`)
Full interactive docs	`GET /docs` (Swagger UI, once authenticated)

Your instance only needs to be assigned and running — open it once from CloudPC.live so it's warm, then everything below works the same whether a human or your code is calling it.

1 Authentication

This instance uses a password gate, not a login form — trade your instance's Share Access Password for a session cookie, then send that cookie with every request.

Get a session cookie

1. Find your instance's Share Access Password in Instance Configuration.

2. Exchange it for a cpc_gate cookie:

POST /auth/login

curl -s -i -X POST "BASE_URL/auth/login" \
  -d "password=YOUR_SHARE_PASSWORD" \
  -c cookies.txt

3. Reuse that cookie jar (or copy the cpc_gate value) on every request below:

curl -s -b cookies.txt "BASE_URL/v1/audio/voices"

Verified live: a real cpc_gate cookie obtained this way authenticated every endpoint on this page, including a real speech generation call.

2 List available voices

See every voice id you can pass to voice below.

GET /v1/audio/voices

curl -s -b cookies.txt "BASE_URL/v1/audio/voices"

Verified live — returns {"status":"ok","voices":["Alice.wav","Ryan.wav", ...]}. Use the exact filename (including .wav) as the voice field below.

3 Generate speech

Same shape as OpenAI's /v1/audio/speech — the response body is the raw audio file, not JSON.

POST /v1/audio/speech

curl -s -b cookies.txt -X POST "BASE_URL/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello from CloudPC text to speech.",
    "voice": "Alice.wav",
    "response_format": "wav"
  }' \
  --output speech.wav

import requests

session = requests.Session()
session.post("BASE_URL/auth/login", data={"password": "YOUR_SHARE_PASSWORD"})

resp = session.post(
    "BASE_URL/v1/audio/speech",
    json={
        "model": "tts-1",
        "input": "Hello from CloudPC text to speech.",
        "voice": "Alice.wav",
        "response_format": "wav",
    },
)
with open("speech.wav", "wb") as f:
    f.write(resp.content)

// After posting to /auth/login once and keeping the cpc_gate cookie
// (e.g. via a cookie-jar-aware fetch client on the server side):
const resp = await fetch("BASE_URL/v1/audio/speech", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Cookie": "cpc_gate=" + gateCookie },
  body: JSON.stringify({
    model: "tts-1",
    input: "Hello from CloudPC text to speech.",
    voice: "Alice.wav",
    response_format: "wav",
  }),
});
const audioBuffer = await resp.arrayBuffer();

from openai import OpenAI

# The openai SDK doesn't support cookie auth directly — log in once with
# requests to get the cpc_gate value, then pass it as a default header.
client = OpenAI(
    base_url="BASE_URL",
    api_key="not-used",
    default_headers={"Cookie": "cpc_gate=" + gate_cookie},
)

resp = client.audio.speech.create(
    model="tts-1",
    voice="Alice.wav",
    input="Hello from CloudPC text to speech.",
)
resp.stream_to_file("speech.wav")

Request fields

Field	Type	Notes
`model`	string	Required by the schema; any value works (e.g. `tts-1`) — there's only one model.
`input`	string	The text to speak.
`voice`	string	A filename from List Voices, e.g. `Alice.wav`.
`response_format`	string	`wav` (default), `opus`, or `mp3`.
`speed`	number	Default `1.0`.
`seed`	integer	Optional — set for reproducible output.
`language`	string	Optional.

Verified live: a real request with voice: "Alice.wav" returned a valid 3.16s 24kHz WAV file that played back the requested text correctly.

Advanced: native endpoint & full docs

The OpenAI-compatible endpoint above covers the common case. For voice cloning from a reference clip, more granular audio processing options, and everything else the engine supports, use the native endpoint instead.

Native endpoint

POST /tts

Same auth (the cpc_gate cookie). Accepts predefined-voice or voice-clone modes and more audio post-processing controls than /v1/audio/speech exposes — see the full parameter list in the interactive docs below.

Interactive API reference

Once you have a cpc_gate cookie (open BASE_URL/docs in a browser tab right after logging in via the app's own password screen), the full Swagger UI documents every endpoint and field with a live "Try it out" button — the fastest way to explore beyond what's on this page.

Notes & troubleshooting

Getting HTML back instead of audio

You're not authenticated. Unlike a typical API, an unauthenticated request to most paths returns the password-entry page as HTML with a 200 status (not a clean 401) — check for an <html> body instead of audio/JSON, and re-run the login step.

`401 {"error":"password required"}`

This one is a clean JSON error — it only happens on /api/* paths (not /v1/audio/* or /tts). Same fix: log in again.

Your instance has to be running

If it's paused or hasn't been opened yet, requests will fail or time out. Start it once from CloudPC.live first.

`422` validation error

Usually a missing required field (model, input, voice) or a voice value that doesn't match a real filename from List Voices exactly.

Generate speech from your own code