وثائق API

التوثيق

وتتطلب جميع طلبات واجهة برمجة التطبيقات التحقق من الهوية عن طريق رمز حامل في قاعدة البيانات. Authorization العنوان.

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

مجموعات برامج الحاسوب

يسهل دمج 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 هي:

حدود المعدلات

وتختلف الحدود القصوى لمعدلات المساعدة المؤقتة حسب الخطة:

وترد عناوين حدود المعدلات في كل رد: 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

الاستجابة

يعيد الملف الصوتي كبيانات ثنائية مع العنوان المناسب Content-Type (audio/mpeg، audio/wav، إلخ).

Content-Type: audio/mpeg
Content-Length: 48256
X-Credits-Used: 2
X-Credits-Remaining: 498

تحويل الكلام إلى نص

يدعم 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"]
}

الدردشة الصوتية

إرسال صوت أو نص وتلقي استجابة الذكاء الاصطناعي مع الكلام المركب.

الهيئة الطالبة (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 متوازية. اختياريا تلقي webhook استدعاء عندما تنتهي جميع الوظائف.

البارامترات

الاستجابة

{
  "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
}

فحص صحي

تحقق من حالة خادم وحدة المعالجة الرسومية، النماذج المحملة، وحجم الصف. لا حاجة للتحقق. مخزن لمدة 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
}

أمثلة على الرموز

• 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
  }
}

الروابط الشبكية

بالنسبة للمهام التي تستغرق وقتاً طويلاً (تقسيم الجذور، وترجمة النصوص بالدفعات)، يمكنك توفير بارامترات webhook_url. وعندما تنتهي المهمة، سنرسل النتيجة إلى عنوان URL الخاص بك.

{
  "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"
}