راهنمای تبدیل متن به گفتار

تبدیل متن به گفتار، متن نوشتاری را برای دستیارها، روایت، دسترس‌پذیری، محتوای آموزشی و پاسخ‌های صوتی به صدای گفتاری تبدیل می‌کند. AvalAI این قابلیت را از طریق endpoint سازگار با OpenAI یعنی /v1/audio/speech و مدل‌های چند ارائه‌دهنده ارائه می‌دهد.

مستندات مرتبط: API صوتی، ساخت برنامه‌های صوتی گفت‌وگومحور، پردازش صوت

انتخاب مدل

خانواده مدل	مناسب برای	نکته‌ها
gpt-4o-mini-tts	کنترل لحن، سرعت، سبک و احساس	برای کنترل سبک با زبان طبیعی از instructions استفاده کنید.
tts-1	ادغام‌های موجود و گفتار سریع	تأخیر کمتر و سازگاری گسترده.
tts-1-hd	TTS سازگار با OpenAI با کیفیت بالاتر	برای روایت و voice-over تولیدی مناسب است.
gemini-2.5-pro-tts / gemini-2.5-flash-tts	routeهای Gemini TTS	وقتی workflow شما روی Gemini audio استاندارد شده مفید است.
eleven_v3، eleven_multilingual_v2، eleven_turbo_v2_5، eleven_flash_v2_5	صداهای ElevenLabs	برای محصولات صوتی گویاتر یا چندزبانه انتخاب خوبی است.
groq.playai-tts / groq.playai-tts-arabic	صداهای PlayAI از مسیر Groq	برای تأخیر کم یا routing خاص ارائه‌دهنده مفید است.

تولید گفتار پایه

Bash

curl https://api.avalai.ir/v1/audio/speech \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "voice": "coral",
    "input": "امروز روز خوبی برای ساختن چیزی است که مردم دوستش داشته باشند.",
    "instructions": "با لحنی گرم و مطمئن صحبت کن.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Python

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    voice="coral",
    input="امروز روز خوبی برای ساختن چیزی است که مردم دوستش داشته باشند.",
    instructions="با لحنی گرم و مطمئن صحبت کن.",
    response_format="mp3",
) as response:
    response.stream_to_file(Path("speech.mp3"))

JavaScript

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const speech = await client.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "coral",
  input: "امروز روز خوبی برای ساختن چیزی است که مردم دوستش داشته باشند.",
  instructions: "با لحنی گرم و مطمئن صحبت کن.",
  response_format: "mp3",
});

await fs.writeFile("speech.mp3", Buffer.from(await speech.arrayBuffer()));

صدا و سبک

• صداهای سازگار با OpenAI شامل alloy، ash، ballad، coral، echo، fable، nova، onyx، sage، shimmer، verse، marin و cedar هستند؛ دسترسی می‌تواند به مدل وابسته باشد.
• برای ارزیابی کیفیت TTS سازگار با OpenAI، ابتدا marin یا cedar را تست کنید و سپس گزینه‌های دیگر را از نظر brand fit، زبان و latency بسنجید.
• tts-1 و tts-1-hd ادغام‌های قدیمی را ساده نگه می‌دارند، اما مجموعه voice کوچک‌تری دارند و همه فیلدهای کنترل سبک را پشتیبانی نمی‌کنند.
• gpt-4o-mini-tts می‌تواند instructions زبان طبیعی را برای لحن، سرعت، احساس، لهجه و نحوه ارائه دنبال کند.
• صداهای ارائه‌دهندگان دیگر مثل ElevenLabs، Gemini و PlayAI ممکن است نام‌ها و محدودیت‌های متفاوتی داشته باشند. اگر یک voice خطا داد، مستندات ارائه‌دهنده را بررسی کنید.
• به کاربران نهایی شفاف بگویید صدایی که می‌شنوند با هوش مصنوعی تولید شده است.

بررسی زبان و تلفظ

TTS سازگار با OpenAI می‌تواند زبان‌های زیادی را تولید کند، اما voiceهای built-in بسته به ارائه‌دهنده و زبان ممکن است بهینه‌سازی متفاوتی داشته باشند. پیش از عرضه workflow صوتی:

• زبان‌های هدف، از جمله فارسی، را با عبارت‌های واقعی محصول و نام کاربران تست کنید.
• راهنمای تلفظ، glossary، عددها و abbreviationها را بین chunkها ثابت نگه دارید.
• برای تست پخش کم‌تاخیر wav یا pcm را ترجیح دهید؛ وقتی حجم ذخیره‌سازی و سازگاری پخش مهم‌تر است mp3 مناسب‌تر است.
• گفتار تولیدشده را با گویشور بومی از نظر لحن برند، تلفظ، سرعت و دسترس‌پذیری review کنید.
• مدل، voice، زبان، دستورهای سبک، فرمت پاسخ و latency را log کنید تا regressionها قابل ردگیری باشند.

وضعیت Custom Voice

OpenAI برای مشتریان واجد شرایط، custom voice مبتنی بر consent را مستند کرده است؛ این مسیر شامل ضبط جداگانه رضایت و نمونه صداست. AvalAI امروز endpointهای ساخت voice را به عنوان قابلیت عمومی ارائه نمی‌کند. مگر اینکه AvalAI پشتیبانی custom voice را برای حساب شما اعلام کند، از voiceهای built-in یا voice IDهای provider-specific استفاده کنید. اگر از هر ارائه‌دهنده‌ای برای ضبط یا clone صدا استفاده می‌کنید، consent صریح، disclosure و audit record را کنار workflow صوتی نگه دارید.

فرمت‌های خروجی

فرمت	کاربرد
mp3	پیش‌فرض، کم‌حجم و سازگار با اکثر پخش‌کننده‌ها.
opus	streaming اینترنتی و ارتباط کم‌تاخیر.
aac	سازگاری با موبایل و پلتفرم‌های رسانه‌ای.
flac	آرشیو lossless.
wav	پخش کم‌تاخیر بدون decoding فشرده.
pcm	pipelineهای صوت خام و سیستم‌های realtime playback.

وقتی شروع سریع پخش مهم است از wav یا pcm استفاده کنید. وقتی حجم ذخیره‌سازی مهم است mp3 مناسب‌تر است.

پخش استریمینگ

endpoint گفتار می‌تواند بایت‌های پاسخ را stream کند تا برنامه لازم نباشد تا تولید کل فایل صبر کند.

تولید گفتار سازگار با OpenAI برای مدل‌های پشتیبانی‌شده stream_format هم دارد. برای playback یا نوشتن فایل، stream باینری audio ساده‌تر است؛ فقط وقتی route شما event-style streaming را پشتیبانی می‌کند و می‌خواهید رویدادهای صوت را هنگام رسیدن پردازش کنید از stream_format: "sse" استفاده کنید. sse برای tts-1 یا tts-1-hd پشتیبانی نمی‌شود.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    voice="alloy",
    input="این پاسخ می‌تواند هنگام تولید پخش شود.",
    response_format="wav",
) as response:
    response.stream_to_file("stream.wav")

JavaScript

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "alloy",
  input: "این پاسخ می‌تواند هنگام تولید پخش شود.",
  response_format: "wav",
});

const output = fs.createWriteStream("stream.wav");
output.write(Buffer.from(await response.arrayBuffer()));
output.end();

متن طولانی

• TTS سازگار با OpenAI در هر input تا ۴٬۰۹۶ کاراکتر می‌پذیرد؛ مدل‌های provider-specific ممکن است محدودیت عملی کمتر یا بیشتری داشته باشند.
• متن‌های طولانی را بر اساس پاراگراف، اسلاید یا scene تقسیم کنید.
• نام گوینده، راهنمای تلفظ و دستور سبک را بین chunkها ثابت نگه دارید.
• مکث‌ها یا sound design را در برنامه خود اضافه کنید، نه با یک request بسیار بزرگ.
• نام فایل chunkهای تولیدشده را همراه با ترتیب ذخیره کنید تا reassemble و retry امن باشد.

ترکیب TTS با Responses

برای نوشتن، بازنویسی، خلاصه‌سازی یا بررسی ابزارمحور متن، ابتدا از /v1/responses استفاده کنید و سپس response.output_text را به /v1/audio/speech بدهید.

Python

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

script = client.responses.create(
    model="gpt-5.5",
    instructions="یک به‌روزرسانی محصول کوتاه برای گفتار بنویس.",
    input="توضیح بده AvalAI از SDKهای سازگار با OpenAI و ارائه‌دهندگان متعدد پشتیبانی می‌کند.",
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-4o-mini-tts",
    voice="coral",
    input=script.output_text,
) as speech:
    speech.stream_to_file(Path("update.mp3"))

صوت در Chat Completions

اگر می‌خواهید یک فراخوانی مدل هم متن و هم صوت را با هم برگرداند، از مدل‌های chat صوتی مانند gpt-audio-mini، gpt-audio یا gpt-audio-1.5 در /v1/chat/completions استفاده کنید. اگر workflow شما بیشتر به reasoning متنی، ابزارها یا state نیاز دارد، اول Responses و سپس TTS را اجرا کنید.

بهترین شیوه‌ها

• وقتی کنترل سبک مهم است از gpt-4o-mini-tts استفاده کنید.
• برای ادغام‌های تولیدی قدیمی‌تر، tts-1 و tts-1-hd را نگه دارید.
• از speed با احتیاط برای narration و accessibility استفاده کنید. Speech سازگار با OpenAI مقدار 0.25 تا 4.0 را می‌پذیرد، اما فهم کاربر معمولا زودتر از محدودیت فنی افت می‌کند.
• صداهای اختصاصی هر ارائه‌دهنده را بعد از تست زبان، تلفظ، latency و الزامات licensing انتخاب کنید.
• مدل، voice، فرمت، طول ورودی، latency و اندازه خروجی را log کنید.
• روایت‌های ثابت را cache کنید تا برای هر پخش دوباره تولید نشوند.
• API key را commit نکنید؛ AVALAI_API_KEY را از environment بخوانید.