API دستاویزات

توثیق

تمام API درخواستوں کو توثیق کی ضرورت ہے Authorization هيڈر.

Authorization: Bearer sk-tts-your-api-key-here

ايس ڈی کي

سرکاری SDKs آپ کی ایپلیکیشن میں TTS.ai کو شامل کرنے کو آسان بناتے ہیں. دونوں ہی اوپن سورس اور GitHub پر دستیاب ہیں.

pip install ttsai

from tts_ai import TTSClient

client = TTSClient(api_key="sk-tts-...")
audio = client.generate(
    text="Hello world!",
    model="kokoro"
)
client.save(audio, "output.wav")

npm install @ttsainpm/ttsai

const { TTSClient } = require('@ttsainpm/ttsai');

const client = new TTSClient({
  apiKey: 'sk-tts-...'
});
const audio = await client.generate({
  input: 'Hello world!',
  model: 'kokoro'
});
await client.saveToFile(audio, 'output.wav');

بنياد URL

تمام انتہا پوائنٹس اس بیس URL کے نسبت ہیں. مثال کے طور پر، TTS انتہا پوائنٹ ہے:

حدیں

API شرح حدوں پلان کے مطابق مختلف ہیں:

ریت حد ہیڈرس ہر جواب میں شامل ہیں: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

کریڈٹ لاگت

تحریر سے کلام

متن کو بولنے والی آڈیو میں تبدیل کریں. درخواست شدہ فارمیٹ میں آڈیو فائل واپس کرتا ہے.

درخواست کا جسم

مثال درخواست

curl -X POST https://api.tts.ai/v1/tts/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kokoro",
    "text": "Hello from TTS.ai! This is a test.",
    "voice": "af_bella",
    "format": "mp3"
  }' \
  --output output.mp3

جواب

The TTS endpoint queues your request and returns a JSON response with a job UUID. You then poll for the result.

Step 1: Submit request

{
  "uuid": "77b71db532874ce98e84a69a2d740d4c",
  "job_id": "f21316bb-aefa-480d-8523-701d1e3184ce",
  "status": "queued",
  "credits_used": 11,
  "credits_remaining": 15000
}

Step 2: Poll for result

Poll this endpoint every 1-2 seconds until status is completed or failed.

{
  "status": "completed",
  "result_url": "https://api.tts.ai/static/downloads/77b71db5.../output.mp3"
}

{
  "status": "processing"
}

Step 3: Download audio

Fetch the result_url from the completed response to download the audio file.

Full example

import requests, time

API_KEY = "sk-tts-your-key"
BASE = "https://api.tts.ai"

# 1. Submit TTS request
resp = requests.post(f"{BASE}/v1/tts/", json={
    "model": "kokoro",
    "text": "Hello from TTS.ai!",
    "voice": "af_bella"
}, headers={"Authorization": f"Bearer {API_KEY}"})
data = resp.json()
uuid = data["uuid"]

# 2. Poll for result
while True:
    result = requests.get(f"{BASE}/v1/speech/results/",
        params={"uuid": uuid}).json()
    if result["status"] == "completed":
        # 3. Download audio
        audio = requests.get(result["result_url"])
        with open("output.mp3", "wb") as f:
            f.write(audio.content)
        break
    elif result["status"] == "failed":
        raise Exception(result.get("error", "Generation failed"))
    time.sleep(1.5)

Streaming alternative: For supported models (Kokoro, MeloTTS), use POST /v1/tts/stream/ for real-time Server-Sent Events (SSE) streaming — no polling needed.

زبان سے متن

آڈیو کو ٹیکس میں تبدیل کریں. خودکار دریافت کے ساتھ 99 زبانوں کی حمایت کرتا ہے.

درخواست کا جسم (multipart/form-data)

جواب

{
  "text": "Hello, this is a transcription test.",
  "language": "en",
  "duration": 3.5,
  "segments": [
    {
      "start": 0.0,
      "end": 1.8,
      "text": "Hello, this is",
      "speaker": "SPEAKER_00"
    },
    {
      "start": 1.8,
      "end": 3.5,
      "text": "a transcription test.",
      "speaker": "SPEAKER_00"
    }
  ]
}

آواز کا کلوننگ

کلونڈ آواز میں بولنا پيدا کريں رفرنس آڊيو اور ٹیکس اپ لوڈ کريں

درخواست کا جسم (multipart/form-data)

جواب

آڈیو فائل کو بائنری ڈیٹا کے طور پر واپس کرتا ہے، جیسا کہ TTS انتہا پوائنٹ.

آواز بدلنے والا

مختلف آواز کے طور پر آواز کے طور پر آڈیو تبدیل کریں. سرچشمہ آڈیو اپ لوڈ کریں اور مقصد آواز منتخب کریں.

درخواست کا جسم (multipart/form-data)

مثال درخواست

curl -X POST https://api.tts.ai/v1/voice-convert/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -F "file=@source_audio.mp3" \
  -F "target_voice=af_bella" \
  -F "model=openvoice" \
  -o converted.wav

جواب

تبدیل شدہ آڈیو فائل کو بائنری ڈیٹا کے طور پر واپس کرتا ہے.

ترجمہ

ایک زبان سے دوسری زبان میں بولی ہوئی آڈیو کا ترجمہ کریں۔ ایک کال میں بولی سے تحریر، ترجمہ اور تحریر سے بولی کا ترکیب کرتے ہیں۔

درخواست کا جسم (multipart/form-data)

جواب

{
  "original_text": "Hello, how are you?",
  "translated_text": "Hola, como estas?",
  "source_language": "en",
  "target_language": "es",
  "audio_url": "https://api.tts.ai/v1/results/translate_abc123.mp3",
  "credits_used": 5
}

کلام سے کلام

مضمون کو محفوظ رکھتے ہوئے بولنے کے انداز ، احساس يا پيش کر نے کو تبديل کريں. تنا ر ، پيسنگ اور اظہار کي ترتيب کے ليے فائده مند

درخواست کا جسم (multipart/form-data)

جواب

تبدیل شدہ آڈیو فائل کو بائنری ڈیٹا کے طور پر واپس کرتا ہے.

آڈیو ٹولز

بہتری کے لیے آڈیو پروسیسنگ انتہا پوائنٹس، آواز کو ہٹانا، سٹیم تقسیم کرنا، اور مزید.

{
  "key": "C",
  "scale": "Major",
  "bpm": 120.0,
  "time_signature": "4/4",
  "camelot": "8B",
  "compatible_keys": ["C Major", "G Major", "F Major", "A Minor"]
}

آواز چیٹ

آڈیو یا ٹیکس بھیجیں اور سنتھسیزڈ کلام کے ساتھ ایک AI جواب حاصل کریں.

درخواست کا جسم (multipart/form-data يا JSON)

جواب

{
  "conversation_id": "conv_abc123",
  "user_text": "What is the capital of France?",
  "ai_text": "The capital of France is Paris.",
  "audio_url": "https://api.tts.ai/v1/audio/tmp/resp_xyz.mp3",
  "credits_used": 3
}

بٹ TTS

TTS کی متوازی پیدائش کے لیے متعدد تحریریں پیش کریں. اختیاری طور پر ایک ویب ہوک کالبیکٹ حاصل کریں جب تمام کام مکمل ہوں.

پرائمرز

جواب

{
  "batch_id": "abc123",
  "total": 3,
  "completed": 0,
  "status": "processing"
}

پو ل ترقی GET /v1/tts/batch/result/؟batch_id=abc123 کے ساتھ

آواز شامل کرنا

ریفرنس آڈیو سے آواز کو داخل کرنے کا پیش-حساب کریں. قریب-حالت پیداوار کے لیے بعد میں آواز کلوننگ درخواستوں میں واپسی embed_id استعمال کریں.

پرائمرز

جواب

{
  "embed_id": "emb_abc123",
  "model": "chatterbox",
  "duration_ms": 450
}

صحت کی جانچ

GPU سرور کی حالت، لوڈ ماڈلز، اور قطار کی سائز چکیں. توثیق کی ضرورت نہیں. 30 سیکنڈ کے لیے کیچ کیا گیا.

جواب

{
  "status": "online",
  "latency_ms": 45,
  "queue_size": 3,
  "models_loaded": ["kokoro", "chatterbox", "cosyvoice2"]
}

ماڈلز کی فہرست

ان کی صلاحیتوں کے ساتھ تمام دستیاب ماڈلز کی فهرست واپس کرتا ہے.

جواب

{
  "models": [
    {
      "id": "kokoro",
      "name": "Kokoro",
      "type": "tts",
      "tier": "standard",
      "languages": ["en", "ja", "ko", "zh", "fr"],
      "supports_cloning": false,
      "supports_streaming": true,
      "credits_per_1k_chars": 2
    },
    {
      "id": "chatterbox",
      "name": "Chatterbox",
      "type": "tts",
      "tier": "premium",
      "languages": ["en"],
      "supports_cloning": true,
      "supports_streaming": true,
      "credits_per_1k_chars": 4
    }
  ]
}

آوازیں شامل کریں

تمام دستیاب آوازوں کی فهرست واپس کرتا ہے، اختیاری طور پر ماڈل یا زبان کے مطابق فلٹر کیا جاتا ہے.

سوالات

جواب

{
  "voices": [
    {
      "id": "af_bella",
      "name": "Bella",
      "model": "kokoro",
      "language": "en",
      "gender": "female",
      "preview_url": "https://api.tts.ai/v1/voices/preview/af_bella.mp3"
    }
  ],
  "total": 142
}

Saved Voices (Persistent Clones)

Upload a reference audio once, get back a persistent voice_id, then reference that id in TTS requests instead of re-uploading audio every call. Ideal for high-volume integrations.

Upload a voice

POST https://tts.ai/api/v1/user-voices/ Auth required

Multipart form. Fields: file (required, 5-30s audio), name (required), language (optional, default en), model (optional — auto-picks cosyvoice2 for zh/ja/ko else openvoice), consent_confirmed (required, any truthy value).

curl -X POST https://tts.ai/api/v1/user-voices/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -F "file=@reference.wav" \
  -F "name=My Narrator" \
  -F "language=en" \
  -F "consent_confirmed=true"

# Response:
{
  "public_id": "uv_a1b2c3d4e5f6",
  "id": 42,
  "name": "My Narrator",
  "model_name": "openvoice",
  "language": "en",
  "reference_audio_url": "https://tts.ai/media/user-voices/....wav",
  "storage_status": "active",
  "created_at": "2026-04-17T03:45:00+00:00"
}

Use the saved voice in TTS

POST to /api/v1/tts/ (NOTE: web VPS host, not api.tts.ai) with user_voice_id. We load your stored audio and route to the cloning pipeline.

curl -X POST https://tts.ai/api/v1/tts/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from my saved voice","user_voice_id":"uv_a1b2c3d4e5f6"}'

# Returns a queued job — poll /v1/speech/results/?uuid=... for the audio URL.

List / delete

GET    https://tts.ai/api/v1/user-voices/           # list your saved voices + quota info
DELETE https://tts.ai/api/v1/user-voices/?public_id=uv_a1b2c3d4e5f6

Archive / reactivate (free)

Archived voices stay in your account but can't be used in TTS. Useful for dormant end users so your list stays clean.

POST https://tts.ai/api/v1/user-voices/uv_a1b2c3d4e5f6/archive/
POST https://tts.ai/api/v1/user-voices/uv_a1b2c3d4e5f6/reactivate/

کوڈ مثالیں

• Python
• JavaScript
• cURL

import requests

API_KEY = "sk-tts-your-key"

# Text to Speech
response = requests.post(
    "https://api.tts.ai/v1/tts/",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "kokoro",
        "text": "Hello from TTS.ai!",
        "voice": "af_bella",
        "format": "mp3"
    }
)

with open("output.mp3", "wb") as f:
    f.write(response.content)

print(f"Credits used: {response.headers.get('X-Credits-Used')}")

# Speech to Text
with open("recording.mp3", "rb") as f:
    response = requests.post(
        "https://api.tts.ai/v1/stt/",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"file": f},
        data={"model": "faster-whisper", "timestamps": "true"}
    )

result = response.json()
print(result["text"])

# Voice Cloning
with open("reference.wav", "rb") as ref:
    response = requests.post(
        "https://api.tts.ai/v1/tts/clone/",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"reference_audio": ref},
        data={
            "text": "This speech uses a cloned voice.",
            "model": "chatterbox"
        }
    )

with open("cloned_output.mp3", "wb") as f:
    f.write(response.content)

const API_KEY = 'sk-tts-your-key';

// Text to Speech
const response = await fetch('https://api.tts.ai/v1/tts/', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'kokoro',
    text: 'Hello from TTS.ai!',
    voice: 'af_bella',
    format: 'mp3'
  })
});

const audioBlob = await response.blob();
const audioUrl = URL.createObjectURL(audioBlob);
const audio = new Audio(audioUrl);
audio.play();

// Speech to Text
const formData = new FormData();
formData.append('file', audioFile);
formData.append('model', 'faster-whisper');

const response = await fetch('https://api.tts.ai/v1/stt/', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: formData
});

const result = await response.json();
console.log(result.text);

# Text to Speech
curl -X POST https://api.tts.ai/v1/tts/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"kokoro","text":"Hello!","voice":"af_bella","format":"mp3"}' \
  -o output.mp3

# Speech to Text
curl -X POST https://api.tts.ai/v1/stt/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -F "file=@recording.mp3" \
  -F "model=faster-whisper" \
  -F "timestamps=true"

# Voice Cloning
curl -X POST https://api.tts.ai/v1/tts/clone/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -F "reference_audio=@reference.wav" \
  -F "text=This uses a cloned voice." \
  -F "model=chatterbox" \
  -o cloned.mp3

# Audio Enhancement
curl -X POST https://api.tts.ai/v1/audio/enhance/ \
  -H "Authorization: Bearer sk-tts-your-key" \
  -F "file=@noisy_audio.mp3" \
  -F "denoise=true" \
  -F "enhance_clarity=true" \
  -o enhanced.mp3

غلطی کوڈ

تمام غلطیاں ایک JSON جواب واپس لائیں error میدان.

{
  "error": {
    "code": "insufficient_credits",
    "message": "You do not have enough characters for this request.",
    "characters_required": 4000,
    "characters_available": 2000
  }
}

ویب ہوکس

طویل عرصے تک چلنے والے کاموں کے لیے (سٹم تقسیم، بیچ TTS)، آپ webhook_url پیرامیٹر فراہم کر سکتے ہیں. جب کام مکمل ہو جائے گا، ہم آپ کے URL پر نتیجے کو POST کریں گے۔

{
  "event": "task.completed",
  "task_id": "task_abc123",
  "status": "success",
  "result_url": "https://api.tts.ai/v1/results/task_abc123",
  "credits_used": 12,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:45Z"
}