API تبدیل متن به صدا و صدا به متن

سه کار صوتی از یک نشانی: گفتار به متن (فایل صوتی را به متن فارسی یا زیرنویس تبدیل کنید)، ترجمهٔ صوت (متن انگلیسی یک صدای غیرانگلیسی) و متن به گفتار (از متن، فایل صوتی بسازید). درخواست‌ها همان شکل API صوتی OpenAI را دارند. صدای فارسی با انتخاب گوینده، رونویسی Scribe و ساخت موسیقی و جلوه صوتی را هم ElevenLabs می‌دهد.

اگر دنبال API تبدیل صدا به متن فارسی برای ویس‌های یک ربات یا فایل جلسه‌ها هستید، از گفتار به متن شروع کنید. برای API تبدیل متن به صدای فارسی، مثلاً پیام تلفن گویا یا خواندن مقاله‌های سایت، بخش متن به گفتار و صداهای فارسی Gemini را بخوانید. هر دو با همان کلید گیسو و از سرور داخل ایران هم کار می‌کنند. اگر فقط می‌خواهید یک متن را بدون برنامه‌نویسی به صدا تبدیل کنید، ابزار تبدیل متن به صدا در اپ گیسو همین کار را می‌کند.

گفتار به متن

فایل را به شکل multipart/form-data در فیلد file بفرستید؛ حداکثر ۲۵ مگابایت، با قالب‌های mp3، mp4، m4a، wav، webm یا ogg.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -F file=@meeting.mp3 \
  -F model=gpt-4o-mini-transcribe \
  -F language=fa

from openai import OpenAI

client = OpenAI(base_url="https://gisoo.pro/api/v1", api_key="sk-gisoo-v1-...")

with open("meeting.mp3", "rb") as audio:
    result = client.audio.transcriptions.create(
        model="gpt-4o-mini-transcribe",
        file=audio,
        language="fa",
        prompt="نام‌ها: گیسو، نِت اَرز، لاراول",   # optional: spellings the model should know
    )
print(result.text)

import fs from "node:fs";

const result = await client.audio.transcriptions.create({
  model: "gpt-4o-mini-transcribe",
  file: fs.createReadStream("meeting.mp3"),
  language: "fa",
});
console.log(result.text);

<?php
$result = $client->audio()->transcribe([
    'model' => 'gpt-4o-mini-transcribe',
    'file' => fopen('meeting.mp3', 'r'),
    'language' => 'fa',
]);
echo $result->text;

کدام مدل

فهرست به‌روز و قیمت‌ها را از GET /models?type=audio_stt بگیرید.

دقت بیشتر در صدای فارسی

• language=fa را بفرستید. بدون آن، مدل زبان را از چند ثانیهٔ اول حدس می‌زند و صدایی که با یک جملهٔ انگلیسی شروع شود، ممکن است به خط لاتین نوشته شود.
• نام‌های خاص را در prompt بنویسید. نام آدم‌ها، برند، شهر و اصطلاح تخصصی جلسه را با املای درست فارسی بدهید تا متن همان‌طور بنویسدشان.
• صدای تمیز مهم‌تر از کیفیت فایل است. یک میکروفون نزدیک به گوینده بیشتر از فایل با بیت‌ریت بالا کمک می‌کند؛ ضبط ۱۶ کیلوهرتز تک‌کاناله برای گفتار کافی است.
• برای جلسهٔ چندنفره gemini-3.5-transcribe را با diarize=true بفرستید تا هر نوبت حرف با برچسب گوینده جدا شود.
• متن پیاده‌شده را یک بار بخوانید. عدد، نام و اصطلاح فنی جاهایی‌اند که مدل بیشتر اشتباه می‌کند؛ پیش از انتشار زیرنویس یا صورتجلسه، همین‌ها را چک کنید.

زیرنویس و زمان‌بندی

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

# Subtitles with timestamps (whisper-1)
curl https://gisoo.pro/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -F file=@lecture.mp3 -F model=whisper-1 -F language=fa \
  -F response_format=srt > lecture.srt

with open("lecture.mp3", "rb") as audio:
    result = client.audio.transcriptions.create(
        model="whisper-1",
        file=audio,
        response_format="verbose_json",
        timestamp_granularities=["word", "segment"],
    )
for seg in result.segments:
    print(f"{seg.start:7.2f}–{seg.end:7.2f}  {seg.text}")

ترجمهٔ صوت به انگلیسی

صدای هر زبانی را می‌گیرد و متن انگلیسی برمی‌گرداند. فقط با whisper-1:

with open("interview-fa.mp3", "rb") as audio:
    english = client.audio.translations.create(model="whisper-1", file=audio)
print(english.text)   # English text of a Persian recording

فایل بزرگ‌تر از ۲۵ مگابایت

صدای گفت‌وگو با کیفیت پایین‌تر هم خوب شنیده می‌شود. فایل را تک‌کاناله و کم‌حجم کنید و اگر هنوز بزرگ بود، تکه‌تکه بفرستید:

# Mono, 32 kbps MP3 — speech stays clear, the file shrinks a lot
ffmpeg -i input.m4a -ac 1 -b:a 32k -ar 16000 small.mp3

# Cut a long recording into 15-minute pieces
ffmpeg -i long.mp3 -f segment -segment_time 900 -c copy part-%02d.mp3

صدای بلند با Gemini

مدل‌های Gemini فایل صوتی را در خود گفت‌وگو می‌پذیرند (بخش input_audio در /chat/completions). مزیتش این است که همان‌جا می‌گویید خروجی چه شکلی باشد: با زمان‌بندی، خلاصه، جدا کردن گوینده‌ها. حجم کل درخواست تا ۲۰ مگابایت است؛ فایل را با دستور ffmpeg بالا کوچک کنید و برای ضبط‌های طولانی تکه‌های ۱۵ دقیقه‌ای بفرستید. Gemini صدا را خودش به کیفیت پایین تبدیل می‌کند، پس کوچک کردن فایل چیزی از دقت کم نمی‌کند.

import base64

with open("voice-note.mp3", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

reply = client.chat.completions.create(
    model="gemini-3.6-flash",
    max_tokens=4000,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcribe this Persian recording with [mm:ss] timestamps every few sentences."},
            {"type": "input_audio", "input_audio": {"data": b64, "format": "mp3"}},
        ],
    }],
)
print(reply.choices[0].message.content)

متن به گفتار

پاسخ خودِ فایل صوتی است (به‌طور پیش‌فرض mp3)، نه JSON. قیمت به‌ازای تعداد نویسه‌های متن است و هر درخواست حداکثر ۴٬۰۹۶ نویسه می‌پذیرد؛ متن بلندتر را به چند تکه بشکنید.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/audio/speech \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "voice": "nova",
    "input": "Your order has shipped and will arrive within two days.",
    "response_format": "mp3"
  }' --output notice.mp3

speech = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="nova",
    input="Your order has shipped and will arrive within two days.",
    instructions="Warm and calm, like a helpful shop assistant.",   # gpt-4o-mini-tts only
)
speech.write_to_file("notice.mp3")

import fs from "node:fs";

const speech = await client.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "nova",
  input: "Your order has shipped and will arrive within two days.",
});
fs.writeFileSync("notice.mp3", Buffer.from(await speech.arrayBuffer()));

صداهای فارسی Gemini

برای فارسی، gemini-3.8-flash-tts را امتحان کنید. همان POST /audio/speech است با همان پارامترها، و سه فرق دارد: صداها نام‌های خودشان را دارند (فهرست پایین)، دستور لحن در instructions جدا از متن می‌رود و بلند خوانده نمی‌شود، و با speakers یک گفت‌وگوی دونفره با دو صدا در یک فایل می‌سازید. هر درخواست تا ۳٬۰۰۰ نویسه می‌پذیرد. خود مدل صدا را با سرعت طبیعی می‌سازد و speed و response_format بعد از ساخت روی فایل اعمال می‌شوند.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

speech = client.audio.speech.create(
    model="gemini-3.8-flash-tts",
    voice="Despina",
    input="سلام، به فروشگاه ما خوش آمدید. سفارش شما ثبت شد و تا دو روز کاری به دستتان می‌رسد.",
    instructions="Warm and calm, like a friendly shop assistant.",   # read as a style, never spoken
    response_format="mp3",
)
speech.write_to_file("welcome-fa.mp3")

curl https://gisoo.pro/api/v1/audio/speech \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "voice": "Charon",
    "input": "به خط پشتیبانی خوش آمدید. برای پیگیری سفارش، عدد یک را بزنید.",
    "instructions": "Clear and even, like a phone menu.",
    "response_format": "wav"
  }' --output ivr-fa.wav

speech = client.audio.speech.create(
    model="gemini-3.8-flash-tts",
    voice="Kore",   # ignored when speakers is set
    input="مریم: امروز دربارهٔ تبدیل متن به صدا حرف می‌زنیم.\nعلی: و این‌که چطور فارسی طبیعی خوانده شود.",
    extra_body={"speakers": [
        {"speaker": "مریم", "voice": "Despina"},
        {"speaker": "علی", "voice": "Charon"},
    ]},
)
speech.write_to_file("podcast-intro.mp3")

• voice نام یکی از صداهای جدول است. نام صداهای OpenAI (مثل nova) هم پذیرفته می‌شود و به یکی از صداهای Gemini می‌رسد؛ نام ناشناخته صدای پیش‌فرض را می‌گیرد.
• در speakers دقیقاً دو نفر با speaker و voice بفرستید و هر خط متن را با «نام: جمله» شروع کنید. خطی که نام ندارد، ادامهٔ حرف گویندهٔ قبلی است.
• هزینهٔ این مدل‌ها بر پایهٔ طول صدای ساخته‌شده است، نه تعداد نویسه؛ مبلغ دقیق هر درخواست در گزارش مصرف می‌آید.

متن فارسی را برای خواندن آماده کنید

مدل همان را می‌خواند که می‌فرستید، پس چند قاعدهٔ ساده در کد خودتان پیش از درخواست، خوانش را از عوض کردن صدا بهتر می‌کند:

• عدد، تاریخ، ساعت و مبلغ را پیش از فرستادن به حروف تبدیل کنید («ساعت دو و نیم»، نه «14:30»).
• نام لاتین را همان‌طور که باید شنیده شود به فارسی بنویسید و برای واژه‌ای که دو تلفظ دارد، اعراب بگذارید؛ یک جدول جایگزینی کوچک در کد برای نام برند و محصول‌هایتان کافی است.
• متن را سر نقطه و علامت سؤال تکه کنید، نه وسط جمله؛ هر تکه را با همان صدا و همان دستور لحن بسازید تا فایل‌ها پشت هم یکدست شنیده شوند.
• فایل‌های کوتاه و تکراری (خوش‌آمد، پیام انتظار، «سفارش شما ثبت شد») را یک بار بسازید و نگه دارید؛ هر بار ساختن دوباره هزینهٔ دوباره دارد.

ElevenLabs: صدای فارسی، Scribe، موسیقی و جلوه صوتی

مدل‌های ElevenLabs روی همان endpointهای بالا (/audio/speech، /audio/transcriptions و /audio/music) و با همان کلید در دسترس‌اند؛ فقط نام مدل را عوض می‌کنید. کلون صدا و دوبله ندارد. فهرست زنده و قیمت‌ها را از GET /models بگیرید.

بعضی ابزارها (افزونه‌ها و برنامه‌هایی که «دریافت فهرست مدل‌ها» دارند) فقط مدل‌های چت را نشان می‌دهند یا فهرست را فیلتر می‌کنند. این مدل‌ها در API هستند؛ شناسهٔ مدل را دستی بنویسید: eleven-v4، eleven-v4-turbo، eleven-v3، eleven-v3-conversational و برای Gemini openrouter/google/gemini-3.1-flash-tts-preview. فهرست فقط صوتی‌ها را با GET /models?type=audio_tts (گفتار) و GET /models?type=audio_stt (رونویسی) می‌گیرید. نام نمایشی مثل «ElevenLabs Eleven v4» شناسه نیست؛ در درخواست همان شناسهٔ انگلیسی را بفرستید.

متن به گفتار با ElevenLabs

• فارسی می‌خوانند: eleven-v4، eleven-v4-turbo، eleven-v3 و eleven-v3-conversational.
• چندزبانه، بدون فارسی: eleven-multilingual-v2، eleven-flash-v2.5 و eleven-turbo-v2.5.
• فقط انگلیسی: eleven-turbo-v2 و eleven-flash-v2.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/audio/speech \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eleven-v3",
    "voice": "mitra",
    "input": "سلام، به فروشگاه ما خوش آمدید. سفارش شما ثبت شد.",
    "language": "fa",
    "response_format": "mp3"
  }' --output welcome-fa.mp3

speech = client.audio.speech.create(
    model="eleven-v3",
    voice="mitra",        # a Persian voice; the default on the four Persian models
    input="سلام، به فروشگاه ما خوش آمدید. سفارش شما ثبت شد.",
    speed=1.0,            # 0.5 to 2
)
speech.write_to_file("welcome-fa.mp3")

هر درخواست تا ۴٬۰۹۶ نویسه می‌پذیرد.

• صداهای فارسی: mitra، arash، arash-clear، mr-o، arman، mahdi، mammo، danesh
• صداهای عربی: adam-ar، heba، sara-ar، abrar
• صداهای انگلیسی: george، sarah، adam، alice، bella، bill، brian، callum، charlie، chris، daniel، eric، harry، jessica، laura، liam، lily، matilda، river، roger، will، christine

رونویسی با Scribe

scribe-v2 و scribe-v2-medical (برای واژگان پزشکی) همان POST /audio/transcriptions را با فایل تا ۲۵ مگابایت می‌گیرند. response_format می‌تواند json، text، verbose_json (زمان هر واژه و بخش‌ها)، diarized_json، srt یا vtt باشد و با diarize=true گوینده‌ها برچسب می‌گیرند. /audio/translations با Scribe کار نمی‌کند.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -F file=@interview.mp3 \
  -F model=scribe-v2 \
  -F language=fa \
  -F diarize=true \
  -F response_format=srt > interview.srt

موسیقی و جلوه صوتی

eleven-music-v1 قطعهٔ موسیقی می‌سازد (seconds از ۳ تا ۳۰۰، پیش‌فرض ۳۰) و eleven-sound-effects-v2 و eleven-sound-effects-v3 جلوهٔ صوتی (seconds از ۰٫۵ تا ۳۰، پیش‌فرض ۵). درخواست و پاسخ همان POST /audio/music است و هزینه به‌ازای طول قطعه حساب می‌شود.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/audio/music \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eleven-music-v1",
    "prompt": "Calm lo-fi piano with soft rain, no vocals",
    "seconds": 60
  }' | jq -r '.data[0].b64_json' | base64 --decode > theme.mp3

curl https://gisoo.pro/api/v1/audio/music \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "eleven-sound-effects-v2", "prompt": "An old wooden door opening slowly", "seconds": 4}' \
  | jq -r '.data[0].b64_json' | base64 --decode > door.mp3

تبدیل صدا (Voice Changer)

POST /audio/voice-change یک فایل صوتی می‌گیرد و همان گفتار را با صدای دیگری برمی‌گرداند؛ کلمه‌ها، زمان‌بندی و احساس گوینده همان می‌ماند و فقط صدا عوض می‌شود. درخواست از نوع multipart/form-data است و کلید و اعتبار (سکه) همان بقیهٔ endpointهای صوتی است.

• eleven-multilingual-sts-v2: ۲۹ زبان؛ فارسی در آن نیست.
• eleven-english-sts-v2: فقط انگلیسی.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/audio/voice-change \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -F file=@input.mp3 \
  -F model=eleven-multilingual-sts-v2 \
  -F voice=george \
  --output out.mp3

پاسخ خودِ فایل صوتی تبدیل‌شده است (مثلاً با Content-Type: audio/mpeg)، نه JSON؛ آن را مستقیم در فایل ذخیره کنید. هزینه به‌ازای مدت صوتِ ورودی حساب می‌شود؛ نرخ هر مدل را از GET /models بگیرید.

• 400 missing_file یا invalid_file: فایل نفرستاده‌اید یا فایل صوتی معتبر نیست.
• 413: فایل از ۲۵ مگابایت بزرگ‌تر است.
• 400 voice_not_available: صدای خواسته‌شده در این endpoint نیست.
• 400 model_endpoint_mismatch: مدلی که فرستاده‌اید برای تبدیل صدا نیست.
• 402: سکهٔ شما کافی نیست.

اگر ElevenLabs خطا بدهد، چیزی از سکهٔ شما کم نمی‌شود. برای این endpoint مدل جایگزین نداریم و همان خطا را می‌بینید.

پرسش‌های پرتکرار

قدم بعدی