Speech to Text

Speech to Text برای تبدیل فایل صوتی به متن استفاده می‌شود. این API با قرارداد رایج OpenAI Whisper سازگار است و از مسیر زیر در گدارAI در دسترس است:

POST /v1/audio/transcriptions

درخواست باید با multipart/form-data ارسال شود. گدارAI مدل را اعتبارسنجی می‌کند، مسیر مناسب ارائه‌دهنده را پیدا می‌کند، مقدار model را برای ارائه‌دهنده بازنویسی می‌کند و فایل صوتی را بدون ثبت محتوای خام به ارائه‌دهنده می‌فرستد.

اطلاع

این مسیر در گدارAI برای مدل‌هایی فعال است که با حالت audio_transcription در فضای کاری شما مجاز شده‌اند. بعضی ارائه‌دهنده‌ها با قرارداد سازگار با OpenAI عبور داده می‌شوند و بعضی از مسیر آداپتر بومی استفاده می‌کنند.

چه زمانی استفاده کنیم؟

از Speech to Text استفاده کنید وقتی می‌خواهید:

پیام صوتی کاربر را به متن تبدیل کنید.
تماس‌های پشتیبانی را قابل جست‌وجو کنید.
متن جلسه را برای خلاصه‌سازی به Chat Completions بدهید.
فایل صوتی را به داده قابل پردازش در سیستم خود تبدیل کنید.

اگر هدف شما ترجمه گفتار به زبان دیگر است، Audio Translation را ببینید. اگر هدف تولید فایل صوتی از متن است، Text to Speech مسیر جداگانه‌ای دارد.

نمونه درخواست

مدل باید از مدل‌های مجاز فضای کاری یا مدل مجازی شما انتخاب شود و mode آن audio_transcription باشد.

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

with open("sample.wav", "rb") as audio:
  response = requests.post(
      "https://YOUR_WORKSPACE.godarai.ir/v1/audio/transcriptions",
      headers={"Authorization": "Bearer YOUR_GODARAI_TOKEN"},
      data={
          "model": "openai:default:gpt-4o-transcribe",
          "language": "fa",
          "response_format": "json",
      },
      files={"file": ("sample.wav", audio, "audio/wav")},
      timeout=120,
  )

response.raise_for_status()
print(response.json()["text"])

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("model", "openai:default:gpt-4o-transcribe");
form.append("language", "fa");
form.append("response_format", "json");
form.append(
"file",
new Blob([await readFile("sample.wav")], { type: "audio/wav" }),
"sample.wav",
);

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/audio/transcriptions", {
method: "POST",
headers: {
  Authorization: "Bearer YOUR_GODARAI_TOKEN",
},
body: form,
});

if (!response.ok) {
throw new Error("Request failed with status " + response.status);
}

const transcription = await response.json();
console.log(transcription.text);

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/audio/transcriptions" --header "Authorization: Bearer YOUR_GODARAI_TOKEN" --form "model=openai:default:gpt-4o-transcribe" --form "language=fa" --form "response_format=json" --form "file=@sample.wav;type=audio/wav"

from openai import OpenAI

client = OpenAI(
  api_key="YOUR_GODARAI_TOKEN",
  base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

with open("sample.wav", "rb") as audio:
  transcription = client.audio.transcriptions.create(
      model="openai:default:gpt-4o-transcribe",
      file=audio,
      language="fa",
      response_format="json",
  )

print(transcription.text)

import { readFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
apiKey: "YOUR_GODARAI_TOKEN",
baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const transcription = await client.audio.transcriptions.create({
model: "openai:default:gpt-4o-transcribe",
file: new File([await readFile("sample.wav")], "sample.wav", { type: "audio/wav" }),
language: "fa",
response_format: "json",
});

console.log(transcription.text);

فیلدهای درخواست

فیلد	وضعیت	توضیح
`model`	اجباری	شناسه مدل صوتی مجاز در گدارAI.
`file`	اجباری	فایل صوتی ورودی.
`language`	اختیاری	زبان گفتار، مثل `fa` یا `en`. اگر زبان را می‌دانید ارسال کنید.
`prompt`	اختیاری	راهنمای کوتاه برای واژه‌های خاص، نام محصول یا زمینه مکالمه.
`response_format`	اختیاری	یکی از `json`، `text`، `srt`، `verbose_json`، `vtt` یا `diarized_json`. مقدار پیش‌فرض `json` است.
`timestamp_granularities[]`	اختیاری	مقدارهای `word` یا `segment`. فقط وقتی معتبر است که `response_format=verbose_json` باشد.
`temperature`	اختیاری	عددی بین `0` و `1`، اگر مدل ارائه‌دهنده پشتیبانی کند.
`stream`	اختیاری	اگر `true` باشد، پاسخ SSE ارائه‌دهنده به صورت جریانی عبور داده می‌شود.
`include[]`	اختیاری	گزینه‌های تکمیلی ارائه‌دهنده، مانند `logprobs`، وقتی مدل پشتیبانی کند.
`chunking_strategy`	اختیاری	تنظیمات chunking برای مدل‌هایی که پردازش طولانی‌تر یا VAD دارند.
`known_speaker_names[]`	اختیاری	نام گوینده‌های شناخته‌شده برای مدل‌هایی که جداسازی گوینده را پشتیبانی می‌کنند.
`known_speaker_references[]`	اختیاری	نمونه مرجع گوینده برای ارائه‌دهنده‌هایی که این قابلیت را دارند.

نکته

اگر زمان‌بندی واژه یا بخش گفتار می‌خواهید، response_format را روی verbose_json بگذارید و timestamp_granularities[] را ارسال کنید. همه ارائه‌دهنده‌ها همه سطح‌های زمان‌بندی را پشتیبانی نمی‌کنند.

ارائه‌دهنده‌های پشتیبانی‌شده

گدارAI در زمان اجرای درخواست به پایگاه داده کشف مدل کوئری نمی‌زند. منبع تصمیم‌گیری مسیر، دسترسی مدل در فضای کاری و حالت audio_transcription است. سپس بر اساس ارائه‌دهنده مقصد، یکی از مسیرهای زیر اجرا می‌شود:

گروه	ارائه‌دهنده‌ها	رفتار در گدارAI
سازگار با OpenAI	`openai`، `azure-open-ai`، `groq`، `mistral-ai`، `together-ai`	درخواست `multipart/form-data` به مسیر `/audio/transcriptions` ارائه‌دهنده عبور داده می‌شود. نام‌های داخلی `azure`، `mistral` و `togetherai` هم به همین گروه نگاشت می‌شوند.
سازگار با OpenAI، در صورت فعال‌بودن در محیط	`openrouter`، `sambanova`، `deepinfra`، `fireworks`	قرارداد عمومی همان است، اما پشتیبانی نهایی به مدل و حساب ارائه‌دهنده فعال در فضای کاری شما بستگی دارد.
آداپتر بومی	`deepgram`	فایل از multipart به بدنه دودویی تبدیل و به `/v1/listen` فرستاده می‌شود. مقدار `language`، اگر ارسال شود، به query منتقل می‌شود و پاسخ به شکل `{ "text": "..." }` نرمال می‌شود.
آداپتر بومی	`cohere`	درخواست به `/v2/audio/transcriptions` فرستاده می‌شود. فیلد `language` برای Cohere اجباری است و پاسخ موفق ارائه‌دهنده عبور داده می‌شود.
آداپتر بومی	`google-vertex`	درخواست به Speech-to-Text v2 `recognize` تبدیل می‌شود و متن خروجی به شکل `{ "text": "..." }` نرمال می‌شود.
پشتیبانی‌نشده در این مسیر	`aws-bedrock`	مدل Nova Sonic برای ارتباط بلادرنگ گفتار به گفتار است، نه رونویسی فایل بارگذاری‌شده؛ بنابراین این مسیر آن را رد می‌کند.

برای google-vertex باید در تنظیمات حساب ارائه‌دهنده یکی از این دو حالت آماده باشد:

project_id، region_name و recognizer_id
یا مقدار کامل recognizer_id به شکل projects/PROJECT_ID/locations/LOCATION/recognizers/RECOGNIZER_ID

هشدار

آداپترهای بومی فعلاً پاسخ جریانی را برای Speech to Text پشتیبانی نمی‌کنند. اگر stream=true را با deepgram، cohere یا google-vertex بفرستید، گدارAI درخواست را با خطای 400 رد می‌کند.

خروجی

در حالت json خروجی ساده معمولاً متن پیاده‌شده را برمی‌گرداند:

{
  "text": "سلام، این یک نمونه پیام صوتی برای آزمایش است."
}

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

{
  "text": "سلام دنیا",
  "language": "fa",
  "duration": 2.4,
  "segments": [
    {
      "id": 0,
      "start": 0,
      "end": 2.4,
      "text": "سلام دنیا"
    }
  ],
  "usage": {
    "type": "tokens",
    "input_tokens": 14,
    "output_tokens": 45,
    "total_tokens": 59
  }
}

اگر response_format را text، srt یا vtt بگذارید، بدنه پاسخ ممکن است متن خام باشد. برای ارائه‌دهنده‌های سازگار با OpenAI، گدارAI Content-Type و بدنه پاسخ موفق ارائه‌دهنده را حفظ می‌کند. در آداپترهای بومی، خروجی می‌تواند نرمال شود؛ برای نمونه deepgram و google-vertex پاسخ را به { "text": "..." } تبدیل می‌کنند.

Streaming

برای مدل‌هایی که پاسخ جریانی تبدیل گفتار به متن را پشتیبانی می‌کنند، stream=true را در فرم بفرستید:

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/audio/transcriptions" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --form "model=openai:default:gpt-4o-transcribe" \
  --form "stream=true" \
  --form "file=@sample.wav;type=audio/wav"

در این حالت پاسخ text/event-stream از ارائه‌دهنده عبور داده می‌شود. این قابلیت فقط برای ارائه‌دهنده‌های سازگار با OpenAI فعال است. اگر مدل انتخابی پاسخ جریانی را پشتیبانی نکند، خطا یا رفتار نهایی را همان ارائه‌دهنده تعیین می‌کند.

نکات عملیاتی

کلید یا مدل باید اجازه audio_transcription داشته باشد؛ مدل chat یا image برای این مسیر پذیرفته نمی‌شود.
فایل صوتی خام، متن استخراج‌شده خام و prompt خام در trace و request log ذخیره نمی‌شود؛ فقط طول، hash کوتاه، نوع محتوا و metadata امن ثبت می‌شود.
مصرف، هزینه و محدودیت نرخ درخواست مثل سایر APIها در گدارAI محاسبه و ثبت می‌شود. اگر ارائه‌دهنده داده مصرف توکنی برگرداند، مصرف نهایی با همان داده نهایی می‌شود.
اگر ارائه‌دهنده خطا بدهد، پیام خطا با قالب سازگار با OpenAI به کلاینت برمی‌گردد.

کیفیت فایل ورودی

کیفیت تبدیل گفتار به متن به فایل ورودی وابسته است. برای نتیجه بهتر:

نویز پس‌زمینه را کم کنید.
اگر ممکن است، از فرمت فشرده‌سازی شدید استفاده نکنید.
زبان گفتار را مشخص کنید.
فایل‌های طولانی را به بخش‌های قابل مدیریت تقسیم کنید.
برای واژه‌های تخصصی، prompt کوتاه و دقیق بدهید.

هشدار

فایل صوتی می‌تواند شامل داده شخصی، اطلاعات مشتری یا مکالمه محرمانه باشد. قبل از ارسال، سیاست نگهداری، دسترسی و حذف فایل و متن پیاده‌شده را در اپلیکیشن خود روشن کنید.

تفاوت با Audio Translation

موضوع	Speech to Text	Audio Translation
هدف	تبدیل گفتار به متن همان زبان	ترجمه گفتار به متن زبانی دیگر
خروجی	متن استخراج‌شده	متن ترجمه‌شده
کاربرد	جست‌وجو، خلاصه‌سازی، بایگانی	فهم محتوای صوتی زبان دیگر

اگر فقط متن فارسی گفتار فارسی را می‌خواهید، Speech to Text انتخاب درست است.

خطاهای رایج

نشانه	علت محتمل	راه‌حل
`multipart/form-data content type is required`	درخواست JSON یا فرم نامعتبر ارسال شده است.	فایل را با `multipart/form-data` و فیلد `file` بفرستید.
`model is required`	فیلد `model` در فرم نیست.	شناسه مدل مجاز فضای کاری را ارسال کنید.
`file is required`	فایل صوتی در فیلد `file` نیست.	نام فیلد فایل را دقیقاً `file` بگذارید.
`Model access denied or unsupported`	مدل برای `audio_transcription` مجاز نیست.	مدل صوتی مناسب یا مجوز کلید را بررسی کنید.
`Streaming audio transcriptions are not supported for provider: ...`	با آداپتر بومی درخواست جریانی فرستاده‌اید.	`stream` را حذف کنید یا از مدل سازگار با OpenAI که پاسخ جریانی را پشتیبانی می‌کند استفاده کنید.
`language is required for cohere audio transcriptions`	مدل Cohere را بدون فیلد `language` فراخوانی کرده‌اید.	زبان گفتار را با مقداری مثل `fa` یا `en` بفرستید.
`recognizer_id is required for google-vertex audio transcriptions`	تنظیمات Speech-to-Text v2 در حساب Google Vertex کامل نیست.	`recognizer_id` را همراه `project_id` و `region_name` تنظیم کنید، یا نام منبع کامل recognizer را بدهید.
پیام شامل `Nova Sonic`	مدل Bedrock Nova Sonic برای این نقطه پایانی مناسب نیست.	برای فایل صوتی از مدل `audio_transcription` دیگری استفاده کنید؛ Nova Sonic به API بلادرنگ جداگانه نیاز دارد.
`timestamp_granularities requires response_format=verbose_json`	زمان‌بندی خواسته‌اید اما خروجی verbose نیست.	`response_format=verbose_json` را اضافه کنید.
خطای ارائه‌دهنده درباره فرمت یا اندازه فایل	فایل با محدودیت مدل سازگار نیست.	فایل را کوتاه‌تر، تمیزتر یا به فرمت رایج‌تر تبدیل کنید.

جمع‌بندی

POST /v1/audio/transcriptions مسیر استاندارد تبدیل صوت به متن در گدارAI است. این مسیر برای ارائه‌دهنده‌های سازگار با OpenAI فایل را به شکل multipart عبور می‌دهد، برای deepgram، cohere و google-vertex از آداپتر بومی استفاده می‌کند، مدل و دسترسی را کنترل می‌کند، میزان مصرف را ثبت می‌کند و داده حساس صوتی و متن استخراج‌شده را در لاگ خام ذخیره نمی‌کند.

چه زمانی استفاده کنیم؟​

نمونه درخواست​

فیلدهای درخواست​

ارائه‌دهنده‌های پشتیبانی‌شده​

خروجی​

Streaming​

نکات عملیاتی​

کیفیت فایل ورودی​

تفاوت با Audio Translation​

خطاهای رایج​

جمع‌بندی​