صدا، موسیقی و گفتار

چهار کاربرد جداگانه

متن به گفتار: Gemini 3.8 Flash TTS، Flash Lite TTS و Gemini 3.1، Eleven v4 و Turbo و Voxtral. صدا به متن: Whisper Large V3 و Turbo. پاسخ صوتی: GPT Audio و Mini. موسیقی: Lyria Clip و Pro. همه در فهرست مدل‌ها دسته‌بندی و تنظیمات مختص خود دارند.

متن به گفتار

POST /v1/studio/audio با مجوز studio:write، شامل model، text، voice و format است. Gemini همهٔ ۳۰ صدای داخلی را دارد؛ ElevenLabs و Voxtral فهرست متفاوتی دارند. GET /v1/models در studio_settings صدای مجاز، قالب‌ها، پشتیبانی instructions و max_speakers را برمی‌گرداند. انتخاب گوینده به اشتراک پرو نیاز ندارد؛ اعتبار کافی لازم است.

import json, os, urllib.request, urllib.error

payload = {
    "model": "google/gemini-3.8-flash-tts",
    "text": "سلام! به ساروی خوش آمدید.",
    "voice": "Sulafat",
    "format": "wav",
    "instructions": "فارسی، گرم و دوستانه، کمی آهسته"
}

request = urllib.request.Request(
    "https://api.sarovi.ir/v1/studio/audio",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
        "Content-Type": "application/json"
    },
    method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=300) as response:
        result = json.load(response)
        print(result)
except urllib.error.HTTPError as error:
    detail = json.load(error)
    raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from error

Gemini 3.8 متن را همان‌طور که نوشته شده می‌خواند. راهنمای لحن، زبان و سرعت را در instructions بنویسید. speed در مدل‌های فعلی باید 1 باشد. ElevenLabs برچسب‌های صوتی داخل متن و Voxtral نسخه‌های احساسی در نام گوینده دارد. سقف متن ۱۲٬۰۰۰ نویسه است؛ ElevenLabs حداکثر ۱۰٬۰۰۰ نویسه.

گفت‌وگو با دو تا هشت گوینده

در turns نوبت‌ها را با text، voice و instructions اختیاری به ترتیب بفرستید. برای هر نقش یک صدای ثابت انتخاب کنید. text اصلی اختیاری است و از نوبت‌ها ساخته می‌شود. همهٔ نوبت‌ها در یک فایل خروجی تحویل می‌شوند.

• یک یا دو صدای متفاوت: مسیر بومی Gemini؛ حداکثر ۴۰ نوبت و مجموع ۱۲٬۰۰۰ نویسه.
• سه تا هشت صدای متفاوت: ساروی هر نوبت را جداگانه می‌سازد و به ترتیب با مکث ۱۵۰ میلی‌ثانیه‌ای ترکیب می‌کند؛ حداکثر ۱۲ نوبت و مجموع ۴٬۰۰۰ نویسه. خروجی WAV تک‌کانالهٔ 24 kHz و 16-bit است؛ pcm هم قابل درخواست است. سقف صوت خام ۲۰ MiB است. این قابلیت ترکیب ساروی است؛ Google همچنان در درخواست بومی حداکثر دو صدا دارد. زمان اجرا و پیوستگی لحن بین نوبت‌ها ممکن است متفاوت باشد. در Studio، «چند گوینده» و سپس «افزودن گوینده» را انتخاب کنید.

import json, os, urllib.request, urllib.error

payload = {
    "model": "google/gemini-3.8-flash-lite-tts",
    "format": "wav",
    "instructions": "فارسی، طبیعی و دوستانه",
    "turns": [
        {
            "text": "سلام، آماده‌اید؟",
            "voice": "Kore"
        },
        {
            "text": "بله، شروع کنیم.",
            "voice": "Puck",
            "instructions": "پرانرژی"
        },
        {
            "text": "من هم آماده‌ام.",
            "voice": "Charon"
        }
    ]
}

request = urllib.request.Request(
    "https://api.sarovi.ir/v1/studio/audio",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["SAROVI_API_KEY"],
        "Content-Type": "application/json"
    },
    method="POST"
)
try:
    with urllib.request.urlopen(request, timeout=300) as response:
        result = json.load(response)
        print(result)
except urllib.error.HTTPError as error:
    detail = json.load(error)
    raise RuntimeError(f"{error.code}: {detail['error'].get('code', detail['error'].get('type', 'HTTP_ERROR'))}") from error

برای بیش از دو صدا، ساخت با حداکثر دو درخواست هم‌زمان و مهلت کلی ۱۸۰ ثانیه انجام می‌شود. مصرف همهٔ نوبت‌ها جمع و یک بار تسویه می‌شود. اگر نوبتی شکست بخورد یا درخواست لغو شود، خروجی ناقص تحویل نمی‌شود و رزرو اعتبار کاربر آزاد می‌شود. بازاجرای خودکار نوبت‌های پولی انجام نمی‌شود؛ شروع دوباره یک ساخت جدید است و ادامه از نوبت شکست‌خورده فعلاً وجود ندارد. برای جلوگیری از ارسال تکراری، Idempotency-Key ثابت همان درخواست را نگه دارید و درخواست پذیرفته‌شده را با request_id پیگیری کنید. تنظیمات GET /v1/models شامل max_speakers، native_max_speakers و assembled_dialogue با سقف‌های همین قابلیت است.

پاسخ صوتی و ورودی فایل

openai/gpt-audio-mini و openai/gpt-audio از همان POST /v1/studio/audio استفاده می‌کنند. text دستور پاسخ است، voice یکی از alloy، echo، fable، onyx، nova، shimmer و format برابر wav است؛ جریان PCM ارائه‌دهنده به فایل WAV قابل پخش تبدیل می‌شود. instructions راهنمای پاسخ و لحن است. audioInput اختیاری شامل audioBase64 و mediaType برابر audio/wav یا audio/mpeg است. این مدل‌ها پاسخ می‌سازند و مخصوص خواندن عین متن نیستند.

پیاده‌سازی گفتار

POST /v1/audio/transcriptions با مجوز audio:write شامل model برابر openai/whisper-large-v3 یا openai/whisper-large-v3-turbo، audioBase64 و mediaType است. language اختیاری مثل fa یا en است؛ با حذف آن زبان خودکار تشخیص داده می‌شود. فایل MP3، WAV، M4A، WebM، OGG، FLAC یا AAC تا ۱۴ مگابایت پذیرفته می‌شود. خروجی text به زبان اصلی گفتار و execution شامل مدل و مصرف اندازه‌گیری‌شده است. فایل خام را Base64 کنید و پیشوند data URL نفرستید.

موسیقی

مدل‌های google/lyria-3-clip-preview و google/lyria-3-pro-preview از Studio audio استفاده می‌کنند. سبک، سازها، حس و آواز را در text توصیف کنید. گویندهٔ انتخابی ندارند و قالب واقعی فایل در پاسخ مشخص است.

فایل، هزینه و حریم خصوصی

output.data بایت‌های Base64 و output.mediaType قالب واقعی فایل است. Gemini برای پخش مرورگری WAV می‌دهد؛ pcm خام برای برنامه‌های تخصصی قابل درخواست است. اگر files در پاسخ باشد، GET /v1/files/{id} با files:read فایل ذخیره‌شدهٔ همان پروژه را دریافت می‌کند. در storage_warning خروجی Base64 همچنان قابل ذخیره است. رزرو اعتبار و تسویه از همان کیف حساب ساروی انجام می‌شود؛ مصرف واقعی ارائه‌دهنده در گزارش ثبت می‌شود. شناسهٔ X-Request-ID را برای پیگیری نگه دارید. گزارش محتوا تابع تنظیمات حریم خصوصی پروژه است. ابتدا نمونهٔ کوتاه امتحان کنید؛ نام صدا کیفیت یکسان فارسی یا جنسیت مشخص تضمین نمی‌کند.

جلسهٔ زنده

POST /v1/realtime/calls با SDP و DELETE همان مسیر با callId برای گفتگوی WebRTC است؛ این مسیر با ساخت فایل صوتی فرق دارد.