پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

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

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

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

انتخاب مدل

خانواده مدل	مناسب برای	نکته‌ها
`gpt-audio-1.5`	کیفیت صدای برتر و کنترل لحن، سرعت و سبک	مدل گفتار سازگار با OpenAI پیشنهادی فعلی.
`gpt-audio`	برنامه‌های صوتی ورودی/خروجی متعادل	صوت سازگار با OpenAI عمومی.
`gpt-audio-mini`	توسعه و قابلیت‌های صوتی پرترافیک	گفتار سازگار با OpenAI کم‌هزینه.
`gemini-3.8-flash-tts`	کیفیت خلاقانه، اجرای احساسی، لهجه‌های منطقه‌ای و گفت‌وگوهای طولانی	انتخاب پیشنهادی برای گفتار خلاقانه؛ ورودی متن و خروجی صوت.
`gemini-3.8-flash-lite-tts`	توان عملیاتی بالا، تأخیر کم و خواندن متن‌های روزمره	انتخاب پیشنهادی برای حجم بالا؛ طرحواره بومی ساختاریافته مشترک با Flash.
`gemini-2.5-pro-tts` / `gemini-2.5-flash-tts`	ادغام‌های موجود Vertex	درخواست‌های قدیمی `/v1/text:synthesize` را حفظ کنید؛ کارهای جدید را به مسیرهای پشتیبانی‌شده ۳٫۸ منتقل کنید.
`eleven_v3`، `eleven_multilingual_v2`، `eleven_turbo_v2_5`، `eleven_flash_v2_5`	صداهای ElevenLabs	برای محصولات صوتی گویاتر یا چندزبانه انتخاب خوبی است.

منسوخ شده: gpt-4o-mini-tts، tts-1 و tts-1-hd منسوخ شده‌اند و دیگر در دسترس نیستند. به gpt-audio-1.5 یا یک مدل Gemini TTS مهاجرت کنید. منسوخ شدن گروهی از مدل‌ها و راهنمای مهاجرت را ببینید.

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

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/audio/speech \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-audio-1.5",
    "voice": "coral",
    "input": "امروز روز خوبی برای ساختن چیزی است که مردم دوستش داشته باشند.",
    "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-audio-1.5",
    voice="coral",
    input="امروز روز خوبی برای ساختن چیزی است که مردم دوستش داشته باشند.",
    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-audio-1.5",
  voice: "coral",
  input: "امروز روز خوبی برای ساختن چیزی است که مردم دوستش داشته باشند.",
  response_format: "mp3",
});

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

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

bash

curl --fail-with-body -sS https://api.avalai.ir/v1/audio/speech \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "voice": {"name": "Zephyr", "languageCode": "en-US"},
    "input": "Welcome to AvalAI. This voice was generated by AI.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

متن انگلیسی نمونه با languageCode: "en-US" هماهنگ است. چون خروجی با پسوند MP3 ذخیره می‌شود، response_format: "mp3" را صریح تعیین کرده‌ایم. برای توان عملیاتی بالاتر، فقط مقدار model را به gemini-3.8-flash-lite-tts تغییر دهید. برای کنترل گوینده و سبک در هر نوبت و رمزگشایی خروجی بومی بر اساس نوع MIME، نمونه TTS بومی را ببینید.

مهاجرت به Gemini 3.8 TTS

برای کاربردهای جدید تبدیل متن به گفتار، gemini-3.8-flash-tts را برای کیفیت خلاقانه، اجرای احساسی، لهجه‌های منطقه‌ای و ثبات گفت‌وگوهای طولانی انتخاب کنید. برای توان عملیاتی بالا، تأخیر کم و خواندن متن‌های روزمره، gemini-3.8-flash-lite-tts مناسب‌تر است. هر دو مدل متن دریافت می‌کنند و صوت تولید می‌کنند؛ برای رونویسی، گفت‌وگو با ورودی صوتی، Live API یا استدلال طراحی نشده‌اند.

AvalAI این مدل‌های TTS را فقط از طریق روش‌های بومی /v1beta/models، مسیر /v1/chat/completions و مسیر /v1/audio/speech ارائه می‌دهد. آن‌ها را به /v1/responses، /v1/messages یا مسیر قدیمی /v1/text:synthesize نفرستید. ابتدا پاسخ را با یک مدل گفت‌وگومحور یا استدلالی جداگانه بنویسید و سپس متن نهایی را به TTS بدهید.

هنگام مهاجرت از gemini-3.1-flash-tts-preview، برای توان عملیاتی بالا Flash-Lite و برای کیفیت خلاقانه Flash را انتخاب کنید. برای جایگزینی gemini-2.5-flash-tts / gemini-2.5-pro-tts در کارهای جدید نیز همین معیار را به کار ببرید، اما طرحواره درخواست و مسیر را تغییر دهید؛ تعویض شناسه مدل در درخواست Vertex کافی نیست. فراخوانی‌های موجود /v1/text:synthesize باید مدل‌ها و طرحواره قدیمی خود را حفظ کنند.
متن ورودی عیناً خوانده می‌شود. دستورهایی مانند Say cheerfully: و پیشوندهایی مانند Speaker 1: ممکن است با صدای بلند خوانده شوند. در درخواست بومی GenerateContent، روی هر بخش متنی speechMetadata: {"speaker": "Host", "style": "Warm and welcoming."} قرار دهید. هر بخش چندگوینده باید یکی از گوینده‌های تعریف‌شده را مشخص کند. دستورهای مداوم نحوه بیان را در style بنویسید؛ برچسب‌های درون‌متنی مانند <laugh>، <sigh> و <short pause> را فقط برای رویدادهای لحظه‌ای صوتی به کار ببرید.
پاسخ بومی غیرجریانی ۳٫۸ به‌طور پیش‌فرض WAV با نوع audio/wav و هدر RIFF است. مقدار inlineData.mimeType را بررسی کنید: بایت‌های رمزگشایی‌شده WAV را مستقیم ذخیره کنید؛ فقط برای PCM16 بدون هدر با نوع audio/L16، هدر WAV با نرخ ۲۴٬۰۰۰ هرتز و یک کانال بسازید. هرگز هدر دوم اضافه نکنید. نمونه بومی هر دو نوع را مدیریت می‌کند.
در Chat Completions از audio.format استفاده کنید، نه response_format مسیر Speech. خروجی pcm16 بخواهید، مقدار choices[0].message.audio.data را رمزگشایی کنید و PCM خام را با ffmpeg -f s16le -ar 24000 -ac 1 -i speech.pcm speech.wav تبدیل کنید. message.content داده صوتی نیست؛ پیشوندی دلخواه را نیز از رشته Base64 حذف نکنید.
مدل gemini-3.1-flash-tts-preview فقط خروجی PCM16 دارد: در /v1/audio/speech مقدار response_format: "pcm" را بفرستید، خروجی را در فایل خام ذخیره و سپس تبدیل کنید. ذخیره این بایت‌ها با نام speech.mp3 آن‌ها را به MP3 تبدیل نمی‌کند.

bash

curl --fail-with-body -sS https://api.avalai.ir/v1/audio/speech \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-tts-preview",
    "voice": "Zephyr",
    "input": "Have a wonderful day!",
    "response_format": "pcm"
  }' \
  --output legacy-speech.pcm

ffmpeg -f s16le -ar 24000 -ac 1 -i legacy-speech.pcm legacy-speech.mp3

صدا و سبک

صداهای سازگار با OpenAI شامل alloy، ash، ballad، coral، echo، fable، nova، onyx، sage، shimmer، verse، marin و cedar هستند؛ دسترسی می‌تواند به مدل وابسته باشد.
برای ارزیابی کیفیت TTS سازگار با OpenAI، ابتدا marin یا cedar را تست کنید و سپس گزینه‌های دیگر را از نظر brand fit، زبان و latency بسنجید.
gpt-audio-1.5، gpt-audio و gpt-audio-mini مدل‌های گفتار سازگار با OpenAI فعلی هستند؛ مدل‌های منسوخ‌شده tts-1، tts-1-hd و gpt-4o-mini-tts دیگر در دسترس نیستند.
صداهای ارائه‌دهندگان دیگر مثل 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" استفاده کنید.

PythonJavaScript

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-audio-1.5",
    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-audio-1.5",
  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

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.6-luna",
    instructions="یک به‌روزرسانی محصول کوتاه برای گفتار بنویس.",
    input="توضیح بده AvalAI از SDKهای سازگار با OpenAI و ارائه‌دهندگان متعدد پشتیبانی می‌کند.",
)

with client.audio.speech.with_streaming_response.create(
    model="gpt-audio-1.5",
    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-audio-1.5 و برای کارهای پرترافیک یا حساس به هزینه از gpt-audio-mini استفاده کنید.
از speed با احتیاط برای narration و accessibility استفاده کنید. Speech سازگار با OpenAI مقدار 0.25 تا 4.0 را می‌پذیرد، اما فهم کاربر معمولا زودتر از محدودیت فنی افت می‌کند.
صداهای اختصاصی هر ارائه‌دهنده را بعد از تست زبان، تلفظ، latency و الزامات licensing انتخاب کنید.
مدل، voice، فرمت، طول ورودی، latency و اندازه خروجی را log کنید.
روایت‌های ثابت را cache کنید تا برای هر پخش دوباره تولید نشوند.
API key را commit نکنید؛ AVALAI_API_KEY را از environment بخوانید.

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

انتخاب مدل ​

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

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

مهاجرت به Gemini 3.8 TTS ​

صدا و سبک ​

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

وضعیت Custom Voice ​

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

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

متن طولانی ​

ترکیب TTS با Responses ​

صوت در Chat Completions ​

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

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

انتخاب مدل

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

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

مهاجرت به Gemini 3.8 TTS

صدا و سبک

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

وضعیت Custom Voice

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

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

متن طولانی

ترکیب TTS با Responses

صوت در Chat Completions

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