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

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

اگر دنبال 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»).
• نام لاتین را همان‌طور که باید شنیده شود به فارسی بنویسید و برای واژه‌ای که دو تلفظ دارد، اعراب بگذارید؛ یک جدول جایگزینی کوچک در کد برای نام برند و محصول‌هایتان کافی است.
• متن را سر نقطه و علامت سؤال تکه کنید، نه وسط جمله؛ هر تکه را با همان صدا و همان دستور لحن بسازید تا فایل‌ها پشت هم یکدست شنیده شوند.
• فایل‌های کوتاه و تکراری (خوش‌آمد، پیام انتظار، «سفارش شما ثبت شد») را یک بار بسازید و نگه دارید؛ هر بار ساختن دوباره هزینهٔ دوباره دارد.

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

قدم بعدی