תיעוד API

אימות

עבור מודלים פרמיה והגבלת קצב גבוהה יותר, אימות עם אסימון Bearer ב Authorization כותרת.

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

SDKs

SDKים רשמיים מקלים על שילוב של 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');

כתובת בסיס

לדוגמה, נקודת הסיום של 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

תגית SSML

עטיפה של מספרים, תאריכים, מטבע, מספרי טלפון, ראשי תיבות ב־ \\ seay- as transcription- as

ברירת המחדל של פורמט התאריך היא etcode\\ comdy > for English and *code*dmy*/ code) במקום אחר; לעקוף עם etcode_format=\\

{
  "model": "kokoro",
  "voice": "af_bella",
  "text": "Your appointment is on <say-as interpret-as=\"date\">2026-04-26</say-as> at <say-as interpret-as=\"time\">14:30</say-as>. Please call <say-as interpret-as=\"telephone\">+1-555-867-5309</say-as> if you need to reschedule."
}

תגובה

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.

דוגמה מלאה

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
}

Batch TTS

שלח טקסטים מרובים עבור דור TTS מקביל. אופציונלית לקבל קריאת הוק אינטרנט בחזרה כאשר כל העבודה הושלמה.

פרמטרים

תגובה

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

התקדמות סקר עם Get/v1/tts/batch/result/? batch_id=abc123

Embeding קול

Comput a coulding voice from reference advord. use the returned embed_id in follow voice revolutions for near-instant generation.

פרמטרים

תגובה

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

בדיקת בריאות

בדוק מצב שרת GPU, מודלים טעונים, וגודל תור. אין צורך באימות. cached במשך 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
}

כתוביות (SRT / VTT) חדש

יצירת כתוביות מסונכרנת עבור כל עבודת TTS הושלמה. מפעילה יישור Whisper על גבי השמע ומחזירה SRT או WebVT. התוצאה היא מטמון בדיסק כך שקריאה שנייה לאותו Uuid היא קריאת דיסק.

פרמטרים שאילתה

curl "https://api.tts.ai/v1/speech/subtitles/?uuid=$UUID&format=srt&download=1" -o subtitles.srt

מילון הגייה חדש

תגיד למנוע TTS איך לבטא מילים ספציפיות רשומות שמורות באופן אוטומטי לכל בקשת TTS שאתה עושה.

מבקש גוף (POST)

# Save an entry
curl -X POST https://tts.ai/api/v1/pronunciations/ \
  -H "Authorization: Bearer sk-tts-..." \
  -H "Content-Type: application/json" \
  -d '{"word": "GIF", "replacement": "jiff"}'

# List your entries
curl https://tts.ai/api/v1/pronunciations/ -H "Authorization: Bearer sk-tts-..."

# Delete entry by id
curl -X DELETE "https://tts.ai/api/v1/pronunciations/?id=42" -H "Authorization: Bearer sk-tts-..."

באפשרותך גם לעבור עקיפה של כל בקשה מבלי לשמור אותם, כולל קידוד )/ conductions (/ code_ conductions) על כל vi1/tts/ call as an object or an array (ראו את endpoint parms).

מאמר קריין חדש

זרוק תווית בודדת של etcrip) / code) על כל עמוד מאמר ומבקרים לקבל בר קריאה קבוע המקריין את הדף בלחיצה. אוטומטי־ מחיק את גוף המאמר, תומך בקול מותאם אישית / תנוחה / צבע מבטא.

<script src="https://tts.ai/narrator.js"
    data-pk="pk-tts-your-publishable-key"
    data-voice="af_bella"
    data-model="kokoro"
    data-extract="auto"
    data-position="bottom"
    data-color="#e60000"
    data-locale="en"></script>

אפשרויות

מקור ב־ GitHub: equia href=\\

הקשב לודג' ט כפתור

NAME OF TRANSLATORS

<script src="https://tts.ai/widget.js"
    data-voice="af_bella"
    data-model="kokoro"
    data-style="full"
    data-theme="light"></script>

קולות שמורים (שכפולים מתמידים)

העלה שמע הפניה פעם אחת, לקבל בחזרה קול_id מתמיד, לאחר מכן התייחסות ש-ID בבקשות TTS במקום להעלות מחדש אודיו כל שיחה. אידיאלי לאינטגרציות נפח גבוה.

העלה קול

POST https://tts.ai/api/v1/user-voices/ Auth נדרש

phports: file (required, 5-30s adio), name (required), language (optional, default en), model (optional value), collections cosy2 for zh/ Ja/ko other opencole), configured_conformated (required, any ruthy 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"
}

השתמש בקול המוצל בטי-טי-אס.

POST to / api/v1/tts/ (NOTE: Web VPS host, not api.tts.ai) with user_could_id. אנו מעמיסים את השמע שלך ואת המסלול לצינור השיבוט.

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.

רשימה / מחק

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 / represent (free) Name

קולות ארכיונים נשארים בחשבון שלך אבל אי אפשר להשתמש בהם בטי-טי-אס, שימושיים למשתמשים רדומים, כך שהרשימה שלך תישאר נקייה.

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

צפנים של שגיאה

כל השגיאות מחזירות תגובה של ג'ייסון עם error שדה.

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

קרסי רשתName

עבור משימות ארוכות טווח (התפלגות סטם, אצווה TTS), באפשרותך לספק פרמטר קידוד >/ 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"
}