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

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

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

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

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

تبدیل گفتار به متن، صوت گفتاری را برای زیرنویس، جستجو، خلاصه‌سازی، تحلیل تماس، گردش‌کارهای پشتیبانی و دسترس‌پذیری به متن تبدیل می‌کند. AvalAI endpointهای رونویسی و ترجمه سازگار با OpenAI را در https://api.avalai.ir/v1 ارائه می‌دهد؛ کافی است در SDKهای OpenAI، base URL را روی AvalAI بگذارید و از AVALAI_API_KEY استفاده کنید.

مستندات مرتبط: API صوتی، پردازش صوت، پردازش صوت در Chat Completions

انتخاب مدل

مدل	مناسب برای	نکته‌ها
`gpt-4o-transcribe`	رونویسی فایل با دقت بالا	از prompt و خروجی `json` / `text` پشتیبانی می‌کند.
`gpt-4o-mini-transcribe`	رونویسی کم‌هزینه‌تر	پیش‌فرض خوب برای بارهای عادی.
`gpt-4o-transcribe-diarize`	transcript با برچسب گوینده	از `response_format="diarized_json"` و برای صوت طولانی از `chunking_strategy="auto"` استفاده کنید.
`whisper-1`	سازگاری گسترده، زیرنویس، ترجمه	از `srt`، `vtt`، `verbose_json` و timestamp کلمه‌ای پشتیبانی می‌کند.
`scribe_v2` / `scribe_v1`	routeهای رونویسی ElevenLabs	وقتی روی مدل‌های صوتی ElevenLabs استاندارد می‌کنید مفید است.
`groq.whisper-large-v3` / `groq.whisper-large-v3-turbo`	routeهای Whisper سازگار با Groq	برای تأخیر کم یا routing خاص ارائه‌دهنده مفید است.

آماده‌سازی صوت

از فرمت‌های رایج مثل mp3، mp4، mpeg، mpga، m4a، wav یا webm استفاده کنید؛ برخی routeهای مرجع سازگار با OpenAI، flac یا ogg را هم می‌پذیرند.
uploadهای سازگار با OpenAI را حداکثر حدود ۲۵ مگابایت نگه دارید؛ فایل‌های طولانی را تقسیم یا فشرده کنید.
صوت تک‌کاناله متمرکز بر گفتار بهتر است؛ سکوت‌های طولانی را حذف کنید و chunkها را وسط جمله نبرید.
برای نام محصول‌ها، اختصارها، زمینه گوینده یا املای مورد انتظار، وقتی مدل انتخابی پشتیبانی می‌کند از prompt کوتاه استفاده کنید. مدل diarization در OpenAI از prompt پشتیبانی نمی‌کند، پس promptهای مربوط به speaker را در مرحله post-processing نگه دارید.
فقط وقتی مدل باید خود صوت را تحلیل کند از input_audio مستقیم در Chat Completions استفاده کنید؛ در غیر این صورت ابتدا رونویسی کنید.

بررسی زبان و قابلیت اعتماد

راهنمای speech-to-text در OpenAI، فارسی و زبان‌های متعدد دیگری را برای رونویسی و ترجمه سبک Whisper فهرست می‌کند، اما کیفیت همچنان به شرایط صدا، لهجه، واژگان تخصصی و route ارائه‌دهنده وابسته است. در AvalAI مدیریت زبان را صریح کنید:

وقتی route پشتیبانی می‌کند و زبان ورودی را می‌دانید، language را تنظیم کنید.
برای نام محصول‌ها، SKUها، acronymها و املای مورد انتظار، glossary کوتاهی در prompt بگذارید؛ برای فایل‌های تقسیم‌شده، اگر مدل prompt را پشتیبانی می‌کند transcript بخش قبلی را به عنوان context بدهید.
برای اصلاح punctuation، تصحیح glossary، classification، extraction یا ترجمه به زبان هدف غیرانگلیسی، از /v1/responses به عنوان مرحله post-processing استفاده کنید.
برای segmentهای کم‌اعتماد، خطاهای مرز گوینده در diarization یا transcriptهای حوزه‌های حساس، صف review انسانی داشته باشید.
پیش از انتخاب route رونویسی ارزان‌تر، نمونه‌های فارسی، mixed-language، نویزی و دارای accent را eval کنید.

رونویسی پایه

BashPythonJavaScript

bash

curl https://api.avalai.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@meeting.mp3" \
  -F model="gpt-4o-transcribe" \
  -F response_format="text" \
  -F prompt="نام محصول‌ها شامل AvalAI، Qwen، Grok، Claude و Gemini است."

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="نام محصول‌ها شامل AvalAI، Qwen، Grok، Claude و Gemini است.",
    )

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: "نام محصول‌ها شامل AvalAI، Qwen، Grok، Claude و Gemini است.",
});

console.log(transcript);

مهاجرت امن از Whisper

مهاجرت pipeline رونویسی فقط تغییر نام مدل نیست؛ یک تغییر سازگاری است. ابتدا endpoint، فایل ورودی و response_format="json" را ثابت نگه دارید و پیش از تغییر prompt، رفتار streaming یا parser پایین‌دستی، خروجی‌ها را مقایسه کنید.

این بخش با اقتباس از مثال رسمی مهاجرت رونویسی از Whisper و مخزن openai/openai-cookbook تهیه شده و endpoint، کلید API، مدل‌های پشتیبانی‌شده و مرزهای پشتیبانی برای AvalAI تطبیق داده شده است.

python

import os

from openai import OpenAI

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


def transcribe(model: str):
    with open("meeting.wav", "rb") as audio_file:
        return client.audio.transcriptions.create(
            model=model,
            file=audio_file,
            response_format="json",
        )


legacy = transcribe("whisper-1")
candidate = transcribe("gpt-4o-transcribe")

print("Whisper:", legacy.text)
print("Candidate:", candidate.text)

مرز مهاجرت را بر اساس قابلیت انتخاب کنید:

نیاز	تصمیم مهاجرت
رونویسی فایل با `json`	`gpt-4o-transcribe` را ارزیابی کنید؛ ابتدا فقط مدل را تغییر دهید و در صورت نیاز متن ساده را از فیلد `.text` پاسخ بخوانید.
`srt`، `vtt`، `verbose_json` یا timestamp کلمه‌ای	تا وقتی route جایگزین صریحاً فرمت لازم را پشتیبانی نکرده، `whisper-1` را نگه دارید.
ترجمه گفتار به متن انگلیسی	مگر اینکه AvalAI مدل ترجمه دیگری فعال کند، `/v1/audio/translations` را با `whisper-1` نگه دارید.
برچسب گوینده	از `gpt-4o-transcribe-diarize` همراه `diarized_json` استفاده کنید؛ این workflow جدا است، نه جایگزینی مستقیم مدل.
متن تدریجی از فایل کامل‌شده	فقط روی route رونویسی GPT-4o سازگار از `stream=true` استفاده کنید و متن را با `transcript.text.done` نهایی کنید.
صوت زنده میکروفون یا تماس	فقط وقتی AvalAI آن route را صریحاً فعال کرده از Realtime استفاده کنید؛ در غیر این صورت chunkهای rolling محدود بفرستید. streaming خروجی فایل، ورودی صوت زنده نیست.

پیش از rollout، baseline مبتنی بر Whisper و مدل candidate را در برابر همان رونویسی مرجع بازبینی‌شده توسط انسان امتیازدهی کنید. نرخ خطای کلمه، تطابق دقیق نام‌ها و اصطلاحات تخصصی، accent، نویز پس‌زمینه، گفتار mixed-language، کامل‌بودن متن نهایی، latency اولین delta و نتیجه نهایی، latency صدک ۹۵، رفتار retry و هزینه و rate limit فعلی را مقایسه کنید. ابتدا فقط مدل را مقایسه کنید، تغییر را به‌صورت canary منتشر کنید و برای فرمت‌های ناسازگار یا regressionها مسیر rollback به whisper-1 را نگه دارید.

فرمت‌های پاسخ

فرمت	چه زمانی استفاده شود	نکته مدل
`json`	پاسخ ساختاریافته همراه با متن می‌خواهید.	پیش‌فرض خوب برای مدل‌های GPT-4o transcription.
`text`	transcript ساده متنی می‌خواهید.	برای pipelineها و scriptها مناسب است.
`verbose_json`	segment یا timestamp لازم دارید.	معمولا با `whisper-1` استفاده می‌شود.
`srt` / `vtt`	فایل زیرنویس لازم دارید.	از `whisper-1` یا routeهای Whisper سازگار استفاده کنید.
`diarized_json`	برچسب گوینده لازم دارید.	از `gpt-4o-transcribe-diarize` استفاده کنید.

برای بررسی confidence، فقط روی مدل‌های GPT-4o transcription سازگار و همراه response_format="json" از include[]=logprobs استفاده کنید. فرض نکنید logprobs، timestamp، diarization و prompt همگی روی یک مدل قابل ترکیب هستند؛ پشتیبانی به مدل و route ارائه‌دهنده وابسته است.

تشخیص گوینده

وقتی workflow پایین‌دستی به نوبت‌های گوینده نیاز دارد، از diarization استفاده کنید. برای ضبط‌های طولانی‌تر از ۳۰ ثانیه، chunking_strategy را "auto" بگذارید.

اگر route انتخابی از reference گوینده شناخته‌شده پشتیبانی کند، می‌توانید clipهای کوتاه ۲ تا ۱۰ ثانیه‌ای را به صورت data URL همراه با known_speaker_names[] و known_speaker_references[] ارسال کنید. همیشه fallback داشته باشید که گوینده‌ها را به شکل عمومی مثل speaker_0 و speaker_1 برچسب بزند، چون پشتیبانی mapping گوینده به حساب و route وابسته است.

مدل diarization فعلی OpenAI یک مدل transcription فایل/request است، نه مدل Realtime transcription. برای live caption فقط وقتی AvalAI route مربوط به Realtime را صریحا فعال کرده از آن استفاده کنید؛ برای گزارش جلسه با speaker label، workflow را روی /v1/audio/transcriptions نگه دارید.

BashPython

bash

curl https://api.avalai.ir/v1/audio/transcriptions \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@meeting.wav" \
  -F model="gpt-4o-transcribe-diarize" \
  -F response_format="diarized_json" \
  -F chunking_strategy="auto" \
  -F 'known_speaker_names[]=agent' \
  -F 'known_speaker_references[]=data:audio/wav;base64,AAA...'

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


def to_data_url(path: str) -> str:
    with open(path, "rb") as speaker_file:
        encoded = base64.b64encode(speaker_file.read()).decode("utf-8")
    return f"data:audio/wav;base64,{encoded}"


with open("meeting.wav", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe-diarize",
        file=audio_file,
        response_format="diarized_json",
        chunking_strategy="auto",
        extra_body={
            "known_speaker_names": ["agent"],
            "known_speaker_references": [to_data_url("agent.wav")],
        },
    )

for segment in transcript.segments:
    print(segment.speaker, segment.start, segment.end, segment.text)

رونویسی استریمینگ

برای recording کامل‌شده‌ای که UI پیش‌رونده می‌خواهد، روی مدل‌های GPT-4o سازگار stream=true تنظیم کنید. whisper-1 از رونویسی stream شده پشتیبانی نمی‌کند. برای میکروفون یا تماس زنده، فقط وقتی route زنده برای حساب شما فعال است از معماری Realtime استفاده کنید؛ در غیر این صورت chunkهای کوتاه rolling را به endpoint رونویسی بفرستید.

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 open("lecture.mp3", "rb") as audio_file:
    stream = client.audio.transcriptions.create(
        model="gpt-4o-mini-transcribe",
        file=audio_file,
        stream=True,
    )

final_text = None

for event in stream:
    if event.type == "transcript.text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "transcript.text.done":
        final_text = event.text

if final_text is None:
    raise RuntimeError("Transcription stream ended without transcript.text.done")

print(f"\nFinal: {final_text}")

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 stream = await client.audio.transcriptions.create({
  model: "gpt-4o-mini-transcribe",
  file: fs.createReadStream("lecture.mp3"),
  stream: true,
});

let finalText = null;

for await (const event of stream) {
  if (event.type === "transcript.text.delta") {
    process.stdout.write(event.delta);
  } else if (event.type === "transcript.text.done") {
    finalText = event.text;
  }
}

if (finalText === null) {
  throw new Error("Transcription stream ended without transcript.text.done");
}

console.log(`\nFinal: ${finalText}`);

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

وقتی می‌خواهید گفتار غیرانگلیسی به متن انگلیسی تبدیل شود، از /v1/audio/translations استفاده کنید. مگر اینکه حساب شما route ترجمه دیگری داشته باشد، whisper-1 را انتخاب کنید.

این endpoint برای خروجی انگلیسی است. برای ترجمه به زبان مقصد دیگر، ابتدا صوت را رونویسی کنید و سپس transcript را با /v1/responses و یک مدل متنی پشتیبان زبان مقصد ترجمه کنید.

BashPython

bash

curl https://api.avalai.ir/v1/audio/translations \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@persian.mp3" \
  -F model="whisper-1"

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("persian.mp3", "rb") as audio_file:
    translation = client.audio.translations.create(
        model="whisper-1",
        file=audio_file,
    )

print(translation.text)

Pipeline با Responses

بعد از داشتن transcript، از /v1/responses برای خلاصه‌سازی، استخراج، دسته‌بندی، tool call یا state چندمرحله‌ای استفاده کنید. این مسیر از انجام همه کارها در یک مدل صوتی قابل‌عیب‌یابی‌تر است.

Python

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("support_call.mp3", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=audio_file,
        response_format="text",
    )

summary = client.responses.create(
    model="gpt-5.5",
    instructions="تماس پشتیبانی را خلاصه کن و action itemها را فهرست کن.",
    input=transcript,
)

print(summary.output_text)

صوت طولانی

فایل‌ها را روی سکوت یا نوبت گوینده تقسیم کنید، نه مرزهای تصادفی بایت.
وقتی پیوستگی مهم است، transcript بخش قبلی را به عنوان prompt بخش بعدی بدهید.
زمان شروع chunkها را ذخیره کنید تا timestampها را بعدا بازسازی کنید.
خطاهای گذرا را با backoff نمایی و نام chunkهای idempotent retry کنید.

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

برای ضبط‌های مهم یا پرنویز از gpt-4o-transcribe استفاده کنید.
برای حجم عادی از gpt-4o-mini-transcribe یا routeهای Groq Whisper استفاده کنید.
برای ترجمه، زیرنویس و workflowهای دارای timestamp زیاد، whisper-1 را نگه دارید.
فقط وقتی برچسب گوینده لازم دارید از diarization استفاده کنید.
مدل، اندازه فایل، مدت، زبان، فرمت پاسخ، latency و تعداد retry را log کنید.
transcriptها را داده کاربر بدانید؛ قبل از ذخیره، فیلدهای حساس را redaction یا محافظت کنید.

برای workflow کامل diarization، استخراج ساختاریافته، اعتبارسنجی evidence و review انسانی، تحلیل هوشمند جلسه با تفکیک گوینده را ببینید.

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

انتخاب مدل ​

آماده‌سازی صوت ​

بررسی زبان و قابلیت اعتماد ​

رونویسی پایه ​

مهاجرت امن از Whisper ​

فرمت‌های پاسخ ​

تشخیص گوینده ​

رونویسی استریمینگ ​

ترجمه به انگلیسی ​

Pipeline با Responses ​

صوت طولانی ​

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

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

انتخاب مدل

آماده‌سازی صوت

بررسی زبان و قابلیت اعتماد

رونویسی پایه

مهاجرت امن از Whisper

فرمت‌های پاسخ

تشخیص گوینده

رونویسی استریمینگ

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

Pipeline با Responses

صوت طولانی

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