Introduction

# KingCong Studio Public TTS API Specification (v1.0)

## 1. System Overview
KingCong Studio provides a unified, high-throughput Text-to-Speech (TTS) REST API capable of synthesizing studio-quality speech and word-level timestamped SRT subtitles across multiple AI speech engines with a single API key:
- **ElevenLabs**: Expressive multilingual speech, emotional nuance, voice cloning (`eleven_multilingual_v2`, `eleven_turbo_v2_5`).
- **MiniMax**: Fast, long-form conversational and storytelling speech (`speech-01-turbo`, `speech-01-hd`).
- **KingCong Studio**: Native Vietnamese voices (e.g., CD Team 2), word-level SRT subtitle export, speed/pitch/vol adjustment (`vieten_speech`, `lingual_speech_v2`).
- **Edge TTS**: Microsoft Azure multi-language voices with 99.9% uptime and high throughput.
- **Kokoro**: Lightweight open-source models with sub-second response times.

---

## 2. Base URL & Authentication
- **Base URL**: `https://api.kingcongstudio.com`
- **Authentication**: All endpoints require an API Key supplied in request headers.
  The API supports any of the following standard header formats:
  ```http
  xi-api-key: kingcongapikey_<48_hex_chars>  ```
  ```http
  Authorization: Bearer kingcongapikey_<48_hex_chars>  ```
  ```http
  X-API-Key: kingcongapikey_<48_hex_chars>  ```
- **Access Prerequisite**: An initial Credit deposit (minimum 50,000 VND) is required on your KingCong Studio account (`https://kingcongstudio.com/ai/kingcong/billing`) to activate API access.

---

## 3. Endpoints Specification

### 3.1 Health Check (Liveness Probe)
Verifies API availability and validates authentication keys.
- **Method**: `GET /v1/health-check`
- **Headers**: `xi-api-key: $API_KEY`
- **Response (200 OK)**:
  ```json
  {
    "status": "success",
    "data": {
      "service": "kingcong-api",
      "ok": true,
      "time": "2026-10-03T02:12:54+00:00"
    }
  }
  ```

### 3.2 Account Credits Balance
Queries remaining character credits associated with the caller's API key.
- **Method**: `GET /v1/credits`
- **Headers**: `xi-api-key: $API_KEY`
- **Response (200 OK)**:
  ```json
  {
    "status": "success",
    "data": {
      "credits": 250000,
      "email": "[email protected]"
    }
  }
  ```

### 3.3 List Supported Providers
Retrieves metadata and supported features for all active speech engines.
- **Method**: `GET /v1/providers`
- **Headers**: `xi-api-key: $API_KEY`

### 3.4 List Models
Retrieves available model IDs filtered by provider.
- **Method**: `GET /v1/models?provider={provider}`
- **Query Parameters**:
  - `provider` (optional): `kingcong` | `elevenlabs` | `minimax` | `edge_tts` | `kokoro`. Omit to return all.

### 3.5 Search & List Voice Library
Fetches paginated voices with search filtering.
- **Method**: `GET /v1/voices`
- **Query Parameters**:
  - `provider` (optional): Filter by provider name.
  - `search` (optional): Substring filter for voice name or language.
  - `page` (optional, default: 1): Page number.
  - `limit` (optional, default: 20, max: 100): Page size.

### 3.6 Create Speech (Text-to-Speech)
Submits an asynchronous text-to-speech task.
- **Method**: `POST /v1/text-to-speech/{voice_id}`
- **Headers**:
  - `Content-Type: application/json`
  - `xi-api-key: $API_KEY`
- **Path Parameter**:
  - `voice_id` (string, required): Unique identifier of target voice (e.g. `BGC20Gf5f36lf17lw2Y1N` for CD Team 2).
- **Request Body (JSON)**:
  ```json
  {
    "text": "Your text to synthesize into natural speech. Minimum 100 characters required for KingCong native engine.",
    "provider": "kingcong",
    "model_id": "vieten_speech",
    "voice_name": "CD Team 2",
    "speed": 1.0,
    "pitch": 1.0,
    "vol": 1.0,
    "export_srt": true,
    "with_transcript": true
  }
  ```
- **Field Constraints**:
  - `text` (string, REQUIRED): Text content. Minimum length is 100 characters when `provider` is `kingcong`.
  - `provider` (string, optional, default: `elevenlabs`): `kingcong`, `elevenlabs`, `minimax`, `edge_tts`, `kokoro`.
  - `model_id` (string, optional): Specific model identifier from `/v1/models`.
  - `voice_name` (string, optional): Display label stored with task metadata.
  - `speed` (float, optional, default: 1.0): Playback rate from `0.5` to `2.0`.
  - `pitch` (float, optional, default: 1.0): Voice pitch adjustment from `0.5` to `1.5`.
  - `vol` (float, optional, default: 1.0): Volume multiplier from `0.1` to `2.0`.
  - `export_srt` (boolean, optional, default: false): Enables word-accurate `.srt` subtitle generation for Vietnamese models.
- **Response (200 OK - Task Submitted)**:
  ```json
  {
    "status": "success",
    "task_id": "Z2v8I9HgPVaIl_2lWZ0Xx",
    "task_status": "pending",
    "credit_cost": 221,
    "new_balance": 7212133,
    "provider": "kingcong",
    "message": "Task created successfully"
  }
  ```

### 3.7 Poll Task Status & Retrieve Audio
Polls task execution status until completion.
- **Method**: `GET /v1/task/{task_id}`
- **Headers**: `xi-api-key: $API_KEY`
- **Status Lifecycle**:
  - `pending` / `queued`: Task is waiting in processing queue.
  - `processing`: AI model is currently rendering audio and subtitles.
  - `done` / `completed`: Synthesis finished. `audio_url` and optional `srt_url` are populated.
  - `failed`: Task failed. Check `error` or `message` property for details. Credits are refunded.
- **Response (200 OK - Completed Task)**:
  ```json
  {
    "status": "success",
    "task_status": "done",
    "progress": 100,
    "audio_url": "https://r2.kingcongstudio.com/users/12/tts_audio/kc_audio_abc123.mp3",
    "srt_url": "https://r2.kingcongstudio.com/users/12/tts_audio/kc_srt_abc123.srt",
    "json_url": "",
    "credit_cost": 221
  }
  ```

### 3.8 List Recent Tasks (History)
- **Method**: `GET /v1/tasks?page=1&limit=20`
- **Headers**: `xi-api-key: $API_KEY`

---

## 4. Production Client Code

### Python Implementation (Task Submission + Polling Loop)
```python
import time
import requests

API_KEY = "kingcongapikey_YOUR_KEY"
BASE_URL = "https://api.kingcongstudio.com"
HEADERS = {
    "Content-Type": "application/json",
    "xi-api-key": API_KEY
}

# 1. Create Speech Task
voice_id = "BGC20Gf5f36lf17lw2Y1N"  # CD Team 2
payload = {
    "text": "Chào mừng bạn đến với KingCong Studio API. Đây là giải pháp chuyển văn bản thành giọng nói tự nhiên với phụ đề SRT chuẩn xác.",
    "provider": "kingcong",
    "model_id": "vieten_speech",
    "voice_name": "CD Team 2",
    "speed": 1.0,
    "export_srt": True
}

res = requests.post(f"{BASE_URL}/v1/text-to-speech/{voice_id}", json=payload, headers=HEADERS)
res_data = res.json()
if res.status_code != 200 or res_data.get("status") != "success":
    raise RuntimeError(f"Task creation failed: {res_data}")

task_id = res_data["task_id"]
print(f"Task submitted successfully! ID: {task_id}")

# 2. Polling Loop
while True:
    poll = requests.get(f"{BASE_URL}/v1/task/{task_id}", headers=HEADERS).json()
    status = poll.get("task_status") or poll.get("status")
    print(f"Polling task status: {status}...")
    
    if status in ("done", "completed"):
        print("Success! Audio URL:", poll.get("audio_url"))
        if poll.get("srt_url"):
            print("Subtitles SRT URL:", poll.get("srt_url"))
        break
    elif status == "failed":
        raise RuntimeError(f"Synthesis failed: {poll.get('error') or poll.get('message')}")
        
    time.sleep(1.5)
```

### TypeScript / Node.js Implementation
```typescript
const API_KEY = "kingcongapikey_YOUR_KEY";
const BASE_URL = "https://api.kingcongstudio.com";

interface TTSResult {
  audioUrl: string;
  srtUrl?: string;
  creditCost: number;
}

async function synthesizeSpeech(text: string, voiceId = "BGC20Gf5f36lf17lw2Y1N"): Promise {
  const headers = {
    "Content-Type": "application/json",
    "xi-api-key": API_KEY
  };

  // 1. Submit Task
  const createRes = await fetch(`${BASE_URL}/v1/text-to-speech/${voiceId}`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      text,
      provider: "kingcong",
      model_id: "vieten_speech",
      speed: 1.0,
      export_srt: true
    })
  });

  const createData = await createRes.json();
  if (!createRes.ok || createData.status !== "success") {
    throw new Error(`TTS creation failed: ${createData.message || createRes.statusText}`);
  }

  const taskId = createData.task_id;

  // 2. Poll until Done
  while (true) {
    await new Promise((resolve) => setTimeout(resolve, 1500));
    const pollRes = await fetch(`${BASE_URL}/v1/task/${taskId}`, { headers });
    const pollData = await pollRes.json();
    const status = pollData.task_status || pollData.status;

    if (status === "done" || status === "completed") {
      return {
        audioUrl: pollData.audio_url,
        srtUrl: pollData.srt_url,
        creditCost: pollData.credit_cost
      };
    }
    if (status === "failed") {
      throw new Error(`TTS synthesis error: ${pollData.error || pollData.message}`);
    }
  }
}
```

---

## 5. HTTP Error Code Reference
| Code | Error Meaning | Resolution |
|:---|:---|:---|
| `401 Unauthorized` | Invalid or absent API key | Check the `xi-api-key` header value |
| `403 Forbidden` | Account has not purchased Credits | Top up credits at `https://kingcongstudio.com/ai/kingcong/billing` to activate API access |
| `400 Bad Request` | Invalid payload or text < 100 chars | Verify input text length and JSON payload structure |
| `404 Not Found` | Target voice ID or task ID not found | Verify voice ID via `GET /v1/voices` |
| `500 Server Error` | Backend speech synthesis failure | Retry request; failed tasks do not deduct credits |

---

## 6. Pricing & Credit Deduction Rates
Billing is strictly consumption-based on character count, base model rate, and optional add-on multipliers:
`Total Credits = Characters × Base Rate × Multipliers`

### 6.1 Base Rates (Credits / Character)
| Engine | Model ID | Display Name | Base Rate (Credits/Char) |
|:---|:---|:---|:---|
| **ElevenLabs** | `eleven_v3` | Eleven v3 | 1.12 |
| ElevenLabs | `eleven_multilingual_v2` | Eleven Multilingual v2 | 1.12 |
| ElevenLabs | `eleven_flash_v2_5` | Eleven Flash v2.5 | 0.56 |
| ElevenLabs | `eleven_turbo_v2_5` | Eleven Turbo v2.5 | 0.56 |
| ElevenLabs | `eleven_turbo_v2` | Eleven Turbo v2 | 0.56 |
| ElevenLabs | `eleven_flash_v2` | Eleven Flash v2 | 0.56 |
| **MiniMax** | `speech-2.8-hd` | MiniMax Speech 2.8 HD | 1.12 |
| MiniMax | `speech-2.6-hd` | MiniMax Speech 2.6 HD | 1.40 |
| MiniMax | `speech-2.5-hd-preview` | MiniMax Speech 2.5 HD | 1.40 |
| MiniMax | `speech-02-hd` | MiniMax Speech 02 HD | 1.40 |
| MiniMax | `speech-01-hd` | MiniMax Speech 01 HD | 1.40 |
| MiniMax | `speech-2.8-turbo` | MiniMax Speech 2.8 Turbo | 1.232 |
| MiniMax | `speech-2.6-turbo` | MiniMax Speech 2.6 Turbo | 1.232 |
| MiniMax | `speech-2.5-turbo-preview` | MiniMax Speech 2.5 Turbo | 1.232 |
| MiniMax | `speech-02-turbo` | MiniMax Speech 02 Turbo | 1.232 |
| MiniMax | `speech-01-turbo` | MiniMax Speech 01 Turbo | 1.232 |
| **KingCong Studio** | `lingual_speech_v2` | KingCong Speech V2 | 1.12 |
| KingCong Studio | `lingual_speech_v1` | KingCong Speech V1 | 1.12 |
| KingCong Studio | `lingual_speech_base` | KingCong Speech Base | 1.12 |
| KingCong Studio | `vieten_speech` | KingCong Vieten Speech | 1.12 |
| KingCong Studio | `jeck_speech` | KingCong Speech+ | 2.24 |

### 6.2 Add-on Multipliers
| Feature Add-on | Multiplier | Notes |
|:---|:---|:---|
| Standard Voice | `x1.00` | Included in base rate |
| Cloned Voice (MiniMax / KingCong) | `x1.15` | Applied when using custom voice clone |
| Export Word-level SRT Subtitles | `x1.15` | Applied when `export_srt: true` or `with_transcript: true` |
| Cloned Voice + Export SRT | `x1.3225` | Compounded multiplier (1.15 × 1.15) |

### 6.3 Quick Examples (Effective Credits / Character)
| Configuration Scenario | Effective Rate (Credits/Char) | Calculation |
|:---|:---|:---|
| ElevenLabs Full (`eleven_v3` / `multilingual_v2`) + SRT | **1.288** | 1.12 × 1.15 |
| ElevenLabs Flash / Turbo + SRT | **0.644** | 0.56 × 1.15 |
| MiniMax HD Cloned Voice | **1.288** | 1.12 × 1.15 |
| MiniMax HD Cloned Voice + SRT | **1.4812** | 1.12 × 1.3225 |
| MiniMax Turbo Cloned Voice | **0.7728** | 0.672 × 1.15 |
| MiniMax Turbo Cloned Voice + SRT | **0.88872** | 0.672 × 1.3225 |
| KingCong Standard Clone (`lingual_speech_v2`) | **1.288** | 1.12 × 1.15 |
| KingCong Standard Clone + SRT | **1.4812** | 1.12 × 1.3225 |
| KingCong Speech+ (`jeck_speech`) + SRT | **2.576** | 2.24 × 1.15 |
| KingCong Speech+ (`jeck_speech`) Clone | **2.576** | 2.24 × 1.15 |
| KingCong Speech+ (`jeck_speech`) Clone + SRT | **2.9576** | 2.24 × 1.3225 |

### 6.4 Cost Estimation for 80,000 Characters
| Configuration Scenario | Total Credits (80k chars) | Effective Rate |
|:---|:---|:---|
| ElevenLabs `eleven_v3` / `eleven_multilingual_v2` | **89,600** | 1.12 |
| ElevenLabs `flash` / `turbo` | **44,800** | 0.56 |
| ElevenLabs Full + SRT | **103,040** | 1.288 |
| ElevenLabs Flash/Turbo + SRT | **51,520** | 0.644 |
| MiniMax HD (Standard) | **89,600** | 1.12 |
| MiniMax Turbo (Standard) | **53,760** | 0.672 |
| MiniMax HD Clone (or HD + SRT) | **103,040** | 1.288 |
| MiniMax Turbo Clone (or Turbo + SRT) | **61,824** | 0.7728 |
| MiniMax HD Clone + SRT | **118,496** | 1.4812 |
| MiniMax Turbo Clone + SRT | **71,098** | 0.88872 |
| KingCong Standard (`lingual_speech_v2`, `vieten_speech`) | **89,600** | 1.12 |
| KingCong Clone (or Standard + SRT) | **103,040** | 1.288 |
| KingCong Clone + SRT | **118,496** | 1.4812 |
| KingCong Speech+ (`jeck_speech`) | **179,200** | 2.24 |
| KingCong Speech+ (`jeck_speech`) + SRT | **206,080** | 2.576 |