مستندات API تبدیل متن به گفتار - نسخه 2

این مستندات نحوه استفاده از API تبدیل متن به گفتار نسخه 2 با صداهای پیشرفته و طبیعی تاک‌بات را توضیح می‌دهد.

نحوه ارسال درخواست

برای ارسال یک درخواست به API نسخه 2، باید یک درخواست HTTP POST به URL زیر ارسال کنید:

$url = 'https://api.talkbot.ir/v2/media/text-to-speech/REQ';

سربرگ‌ها (Headers)

شما باید سربرگ Authorization را با توکن Bearer خود تنظیم کنید:

$headers = [
    'Authorization: Bearer YOUR_ACCESS_TOKEN'
];

داده‌های POST

داده‌های زیر را باید به عنوان بخشی از بدنه درخواست POST ارسال کنید:

$data = [
    'text' => 'متن فارسی شما اینجا قرار می‌گیرد.',
    'voice_id' => 'parsa'  // شناسه صدای مورد نظر
];

لیست صداهای موجود

در جدول زیر تمام صداهای موجود در نسخه 2 همراه با جنسیت و سطح دسترسی مورد نیاز آورده شده است:

مثال‌های کد

<?php
$headers = [
    'Authorization: Bearer YOUR_API_KEY' // کلید API خود را جایگزین کنید
];

$data = [
    'text' => 'سلام، این یک متن نمونه برای تبدیل به گفتار با صدای پارسا است.',
    'voice_id' => 'parsa'
];

$url = 'https://api.talkbot.ir/v2/media/text-to-speech/REQ';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if(curl_errno($ch)){
    echo 'خطای CURL: ' . curl_error($ch);
} else {
    $result = json_decode($response, true);
    if(isset($result['response']['download'])) {
        echo 'فایل صوتی: ' . $result['response']['download'];
    } else {
        echo 'خطا: ' . $response;
    }
}

curl_close($ch);
?>

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'  # کلید API خود را جایگزین کنید
}

data = {
    'text': 'سلام! این یک متن نمونه برای تست API نسخه 2 با صدای آریانا است.',
    'voice_id': 'ariana'
}

url = 'https://api.talkbot.ir/v2/media/text-to-speech/REQ'

response = requests.post(url, headers=headers, data=data)

if response.status_code == 200:
    result = response.json()
    if 'response' in result and 'download' in result['response']:
        print(f"فایل صوتی: {result['response']['download']}")
    else:
        print(f"خطا: {response.text}")
else:
    print(f'خطا: {response.status_code} - {response.text}')

const fetch = require('node-fetch');
const FormData = require('form-data');

const headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
};

const formData = new FormData();
formData.append('text', 'سلام، این یک متن تستی برای تبدیل به گفتار است.');
formData.append('voice_id', 'parsa');

const url = 'https://api.talkbot.ir/v2/media/text-to-speech/REQ';

fetch(url, {
    method: 'POST',
    headers: headers,
    body: formData
})
.then(response => response.json())
.then(data => {
    if(data.response && data.response.download) {
        console.log('فایل صوتی:', data.response.download);
    } else {
        console.log('خطا:', data);
    }
})
.catch(error => {
    console.error('خطا:', error);
});

پاسخ API

پاسخ API به صورت یک رشته JSON خواهد بود که شامل اطلاعاتی درباره فایل صوتی تولید شده و وضعیت درخواست است.

نمونه خروجی موفق:

{
    "response": {
        "code": 200,
        "message": "Success",
        "id": "TTSTALKBOT_V2_tts-parsa-1234567890.wav",
        "download": "https://talkbot.ir/tts_temp/tts-parsa-1234567890.wav",
        "voice_used": "parsa"
    }
}

نمونه خروجی خطا - احراز هویت ناموفق:

{
    "error": {
        "code": 401,
        "message": "Authentication failed",
        "description": "Authorization header is required. Please include a valid Bearer token."
    }
}

نمونه خروجی خطا - عدم دسترسی به صدا:

{
    "error": {
        "code": 403,
        "message": "Access denied",
        "description": "Your subscription plan does not include access to this voice. Please upgrade your plan."
    }
}

نمونه خروجی خطا - اشتراک منقضی شده:

{
    "error": {
        "code": 403,
        "message": "Subscription expired",
        "description": "Unfortunately, your Talkbot AI API package has expired. Please proceed to renew your account."
    }
}

راهنمای انتخاب صدا

برای کمک به انتخاب بهترین صدا برای نیازهای خود، توصیه‌های زیر را مطالعه کنید:

نکات مهم

• حداکثر طول متن ورودی: 5000 کاراکتر
• فرمت خروجی: WAV با کیفیت استودیویی
• زبان پشتیبانی شده: فارسی
• هزینه: 150 توکن به ازای هر 100 کاراکتر
• محدودیت نرخ درخواست بستگی به نوع اشتراک شما دارد
• فایل‌های تولید شده برای 24 ساعت در دسترس خواهند بود

پشتیبانی و تماس

برای هرگونه سوال یا مشکل در استفاده از API، می‌توانید با تیم پشتیبانی تاک‌بات از طریق وب‌سایت talkbot.ir تماس بگیرید.

آزمایش رایگان:

برای آزمایش و تست رایگان این وب سرویس (API) ابتدا در سایت ثبتنام کنید، و سپس از طریق کنترل پنل کاربری، کلید اختصاصی خود را ایجاد کنید. پس از ایجاد کلید، آن را در نمونه کدهای بالا جایگزاری کرده و خروجی را مشاهده کنید. امکان استفاده از کلید آزمایشی فقط تا 15000 توکن میسر است.

سایر وب سرویس ها:

با خرید بسته یاقوتی و یا یکی از بسته های فرایاقوتی، شما علاوه بر وب سرویس یا API پیش رو، از وب سرویس های زیر نیز میتوانید استفاده کنید.