وثائق تطبيق برمجة التطبيقات

التوثيق

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

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

العنوان الشبكي الأساسي

جميع النقاط النهائية هي نسبية لهذا العنوان URL الأساسي. على سبيل المثال، نقطة نهاية 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
}

قائمة النماذج

يعيد قائمة بجميع النماذج المتاحة مع قدراتها.

الاستجابة

{
  "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 credits for this request.",
    "credits_required": 4,
    "credits_available": 2
  }
}

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

بالنسبة للمهام التي تستغرق وقتاً طويلاً (تقسيم الجذور، وترجمة النصوص بالدفعات)، يمكنك توفير بارامترات 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"
}