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

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

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

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

پردازش صوتی

workflowهای صوتی AvalAI شامل تبدیل متن به گفتار، تبدیل گفتار به متن، چت صوتی و pipelineهایی است که transcription، reasoning و تولید گفتار را ترکیب می‌کنند. مستندات صوتی OpenAI این مسیرها را به دو معماری اصلی تقسیم می‌کند: APIهای request-based برای فایل‌ها یا تولید گفتار محدود، و sessionهای Realtime برای صوت زنده با تأخیر کم. در AvalAI امروز، تا وقتی پشتیبانی Realtime صراحتا اعلام نشده، از endpointهای request-based و مدل‌های صوتی Chat Completions استفاده کنید.

انتخاب معماری مناسب

هدف	مسیر AvalAI	نکته
تبدیل متن به فایل صوتی	`/v1/audio/speech`	مناسب برای روایت، accessibility، گفتار دستیار و فایل‌های قابل cache.
رونویسی فایل صوتی	`/v1/audio/transcriptions`	مناسب برای زیرنویس، یادداشت، جستجو، تحلیل و پردازش پس از تماس.
ترجمه گفتار به متن انگلیسی	`/v1/audio/translations`	وقتی خروجی انگلیسی از صوت غیرانگلیسی می‌خواهید از `whisper-1` استفاده کنید.
افزودن ورودی/خروجی صوتی به چت	`/v1/chat/completions` با مدل صوتی	از `modalities`، `audio` و `input_audio` استفاده کنید؛ این مثال‌ها را روی Chat Completions نگه دارید.
استفاده از Responses برای reasoning دستیار صوتی	رونویسی → `/v1/responses` → TTS	وقتی ابزارها، state، خروجی ساختاریافته یا reasoning بعد از تبدیل گفتار به متن لازم است.
ساخت تجربه گفتار-به-گفتار زنده	sessionهای realtime وقتی در دسترس باشند	OpenAI برای voice agent، ترجمه زنده و transcription زنده از Realtime استفاده می‌کند؛ پشتیبانی AvalAI را تا زمان اعلام رسمی فرض نکنید.

خانواده مدل‌های صوتی فعلی

AvalAI مدل‌های صوتی را از طریق model catalog ارائه می‌کند. برای دسترسی دقیق و قیمت، /v1/models یا صفحه provider مربوط را بررسی کنید.

خانواده	نمونه مدل‌ها	کاربرد
TTS شرکت OpenAI	`gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`	تبدیل متن به گفتار عمومی و گفتار کم‌تأخیر.
TTS ارائه‌دهندگان دیگر	`eleven_v3`, `eleven_multilingual_v2`, `eleven_flash_v2_5`, `gemini-2.5-flash-preview-tts`, `groq.playai-tts`	کیفیت صدا، چندزبانه، و voiceهای provider-specific.
رونویسی	`gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-transcribe-diarize`, `whisper-1`, `scribe_v2`	رونویسی فایل، diarization، زیرنویس و analytics.
چت صوتی	`gpt-audio-1.5`, `gpt-audio-mini`	ورودی/خروجی صوتی داخل Chat Completions.

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

Text-to-speech سه ورودی اصلی دارد: model، input و voice. برای مدل‌های سازگار، از instructions برای کنترل tone، pacing، emotion یا سبک بیان استفاده کنید. همچنین در تجربه کاربری به کاربر اطلاع دهید صدایی که می‌شنود با هوش مصنوعی تولید شده است.

برای TTS سازگار با OpenAI، هر درخواست را زیر ۴٬۰۹۶ کاراکتر نگه دارید، وقتی کیفیت مهم است ابتدا marin یا cedar را امتحان کنید، و tts-1 / tts-1-hd را مدل‌های سازگاری با گزینه‌های کنترل سبک کمتر بدانید. اگر route انتخابی speed را پشتیبانی می‌کند، از 1.0 شروع کنید و فقط بعد از تست شنیداری تغییر دهید؛ بازه فنی می‌تواند از محدوده‌ای که کاربر راحت می‌فهمد بزرگ‌تر باشد.

PythonJavaScriptBash

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",
)

speech_file = Path("speech.mp3")

audio = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="alloy",
    input="به AvalAI خوش آمدید. این صدا توسط هوش مصنوعی تولید شده است.",
    instructions="Speak clearly in a warm, professional tone.",
)

audio.stream_to_file(speech_file)
print(f"Saved {speech_file}")

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 audio = await client.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "alloy",
  input: "به AvalAI خوش آمدید. این صدا توسط هوش مصنوعی تولید شده است.",
  instructions: "Speak clearly in a warm, professional tone.",
});

const buffer = Buffer.from(await audio.arrayBuffer());
await fs.promises.writeFile("speech.mp3", buffer);

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": "alloy",
    "input": "به AvalAI خوش آمدید. این صدا توسط هوش مصنوعی تولید شده است.",
    "instructions": "Speak clearly in a warm, professional tone."
  }' \
  --output speech.mp3

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

برای پخش عمومی از mp3، برای streaming اینترنتی از opus، برای موبایل/ویدیو از aac، برای آرشیو lossless از flac، و وقتی latency و هزینه decoding مهم است از wav یا pcm استفاده کنید.

وقتی playback پیش‌رونده می‌خواهید، از streaming helperهای SDK یا stream باینری audio پیش‌فرض استفاده کنید. فقط وقتی مدل و route AvalAI صریحا پشتیبانی می‌کنند، سراغ stream_format: "sse" برای speech streaming مبتنی بر event بروید.

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

برای فایل‌های محدود از /v1/audio/transcriptions استفاده کنید. راهنمای OpenAI بین transcription فایل و transcription زنده Realtime تفاوت می‌گذارد: فایل ساده‌تر است، اما live transcript delta به معماری session-oriented نیاز دارد.

از فرمت‌های upload پشتیبانی‌شده مثل mp3، mp4، mpeg، mpga، m4a، wav یا webm استفاده کنید و uploadهای سازگار با OpenAI را حداکثر حدود ۲۵ مگابایت نگه دارید. برای ضبط‌های طولانی‌تر، فایل را روی مرز جمله یا turn تقسیم کنید تا context در prompt و خلاصه‌سازی downstream منسجم بماند.

PythonJavaScriptBash

python

import os
from openai import OpenAI

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

with open("meeting.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=audio_file,
        response_format="text",
        prompt="This is a support meeting about AvalAI billing and API usage.",
    )

print(transcript)

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 transcript = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("meeting.mp3"),
  response_format: "text",
  prompt: "This is a support meeting about AvalAI billing and API usage.",
});

console.log(transcript);

bash

curl https://api.avalai.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -F file="@meeting.mp3" \
  -F model="gpt-4o-transcribe" \
  -F response_format="text" \
  -F prompt="This is a support meeting about AvalAI billing and API usage."

Diarization و timestamp

وقتی transcript با speaker label لازم دارید، از gpt-4o-transcribe-diarize استفاده کنید.
برای segmentهای دارای speaker و start/end، diarized_json درخواست کنید.
برای ورودی‌های طولانی‌تر diarization، chunking_strategy="auto" را تنظیم کنید.
برای timestampهای word-level، از whisper-1 همراه response_format="verbose_json" و timestamp_granularities[] استفاده کنید.
برای نام محصول، acronym، سبک املایی یا context بخش قبلی، از prompt استفاده کنید. پشتیبانی از prompt به مدل بستگی دارد و مدل diarization در OpenAI از آن پشتیبانی نمی‌کند.
stream=true را streaming برای recording کامل‌شده روی مدل‌های غیر Whisper سازگار بدانید. whisper-1 از رونویسی stream شده پشتیبانی نمی‌کند؛ رونویسی live microphone یا call به route Realtime نیاز دارد.

ترجمه

وقتی از صوت یک زبان دیگر، متن انگلیسی می‌خواهید از /v1/audio/translations استفاده کنید.

PythonJavaScriptBash

python

with open("customer_call_fa.m4a", "rb") as audio_file:
    translation = client.audio.translations.create(
        model="whisper-1",
        file=audio_file,
    )

print(translation.text)

javascript

const translation = await client.audio.translations.create({
  model: "whisper-1",
  file: fs.createReadStream("customer_call_fa.m4a"),
});

console.log(translation.text);

bash

curl https://api.avalai.ir/v1/audio/translations \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -F file="@customer_call_fa.m4a" \
  -F model="whisper-1"

صدا در Chat Completions

وقتی مدل باید audio را مستقیم دریافت کند یا مستقیم audio برگرداند، workflow را روی /v1/chat/completions نگه دارید. این مورد را با یک فراخوانی متنی ساده Responses جایگزین نکنید.

PythonJavaScript

python

import base64
import os
from openai import OpenAI

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

with open("question.wav", "rb") as audio_file:
    encoded_audio = base64.b64encode(audio_file.read()).decode("utf-8")

completion = client.chat.completions.create(
    model="gpt-audio-1.5",
    modalities=["text", "audio"],
    audio={"voice": "alloy", "format": "wav"},
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Answer this voice question briefly."},
                {
                    "type": "input_audio",
                    "input_audio": {"data": encoded_audio, "format": "wav"},
                },
            ],
        }
    ],
)

message = completion.choices[0].message
print(message.content)

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 encodedAudio = fs.readFileSync("question.wav").toString("base64");

const completion = await client.chat.completions.create({
  model: "gpt-audio-1.5",
  modalities: ["text", "audio"],
  audio: { voice: "alloy", format: "wav" },
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Answer this voice question briefly." },
        {
          type: "input_audio",
          input_audio: { data: encodedAudio, format: "wav" },
        },
      ],
    },
  ],
});

console.log(completion.choices[0].message.content);

مسیر مهاجرت به Responses

از Responses زمانی استفاده کنید که audio به text تبدیل شده، یا پیش از TTS وقتی دستیار به reasoning، tool، state یا خروجی ساختاریافته نیاز دارد.

PythonJavaScript

python

with open("question.wav", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=audio_file,
        response_format="text",
    )

answer = client.responses.create(
    model="gpt-5.5",
    instructions="Answer as a concise support assistant.",
    input=f"User said: {transcript}",
)

speech = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="alloy",
    input=answer.output_text,
)

speech.stream_to_file("answer.mp3")

javascript

const transcript = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("question.wav"),
  response_format: "text",
});

const answer = await client.responses.create({
  model: "gpt-5.5",
  instructions: "Answer as a concise support assistant.",
  input: `User said: ${transcript}`,
});

const speech = await client.audio.speech.create({
  model: "gpt-4o-mini-tts",
  voice: "alloy",
  input: answer.output_text,
});

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

نکات طراحی Realtime

مستندات Realtime شرکت OpenAI صوت زنده را به sessionهای voice-agent، translation و transcription تقسیم می‌کند. تا وقتی endpointها و مدل‌های Realtime در AvalAI در دسترس اعلام نشده‌اند، این موارد را فقط مرجع معماری بدانید. /v1/realtime، /v1/realtime/translations، SIP یا مثال‌های client secret را به‌عنوان مسیر اجرایی AvalAI مستند نکنید مگر اینکه AvalAI همان route را رسما اعلام کند.

نوع session در Realtime	چه زمانی استفاده می‌شود	جایگزین سازگار با AvalAI امروز
Voice-agent session	دستیار باید گوش کند، پاسخ صوتی بدهد، tool call انجام دهد و turn state را مدیریت کند.	رونویسی → `/v1/responses` با ابزار/state → `/v1/audio/speech`.
Translation session	برنامه باید گفتار ورودی را به‌صورت پیوسته ترجمه کند.	برای فایل‌های محدود از `/v1/audio/translations` استفاده کنید، یا chunkهای کوتاه را transcribe و متن را با `/v1/responses` ترجمه کنید.
Transcription session	به transcript delta زنده بدون گفتار دستیار نیاز دارید.	برای recordingهای کامل از `/v1/audio/transcriptions` همراه `stream=true` استفاده کنید، یا از server خود chunkهای rolling بفرستید.

transport را بر اساس محل capture صدا انتخاب کنید: WebRTC برای browser/mobile، WebSocket برای pipelineهای media سمت server، و SIP برای telephony. تا وقتی AvalAI این transportها را ارائه نکرده، browser و تلفن را به backend خودتان وصل نگه دارید و AvalAI را فقط با API key سمت server فراخوانی کنید.

برای سیستم‌های زنده، این موارد را از قبل طراحی کنید:

credential کوتاه‌عمر برای clientهای browser/mobile،
safety identifier پایدار و حفظ‌کننده حریم خصوصی برای monitoring و enforcement در سطح کاربر،
turn detection یا voice activity detection صریح،
interruption handling و eventهای partial transcript،
اندازه‌گیری latency جدا از کیفیت transcript یا translation،
لاگ transcript، صدای تولیدشده، tool callها و feedback کاربر.

اگر از integration بتای قدیمی OpenAI Realtime مهاجرت می‌کنید، این کار را از پذیرش AvalAI جدا نگه دارید: headerهای مختص beta را حذف کنید، event nameها و شکل session را به‌روز کنید، و قبل از انتقال traffic دقیقا همان مدل، route، فرمت صوت و مسیر recovery خطا را دوباره تست کنید.

چک‌لیست Production

به کاربر اعلام کنید صدا با هوش مصنوعی تولید شده است.
API key را روی server نگه دارید؛ key بلندمدت را در browser یا mobile قرار ندهید.
نوع، اندازه و مدت فایل صوتی را قبل از ارسال به API validate کنید.
قوانین consent و privacy را برای ضبط تماس، diarization و صدای تولیدشده رعایت کنید.
برای نام‌ها، اصطلاحات محصول و acronymها prompt دامنه‌ای بدهید.
کیفیت transcription را با accent، زبان، noise و vocabulary واقعی ارزیابی کنید.
خروجی voice را از نظر pronunciation، tone، latency و فهم کاربر تست کنید.

پردازش صوتی ​

انتخاب معماری مناسب ​

خانواده مدل‌های صوتی فعلی ​

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

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

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

Diarization و timestamp ​

ترجمه ​

صدا در Chat Completions ​

مسیر مهاجرت به Responses ​

نکات طراحی Realtime ​

چک‌لیست Production ​

منابع مرتبط ​

پردازش صوتی

انتخاب معماری مناسب

خانواده مدل‌های صوتی فعلی

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

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

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

Diarization و timestamp

ترجمه

صدا در Chat Completions

مسیر مهاجرت به Responses

نکات طراحی Realtime

چک‌لیست Production

منابع مرتبط