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

با endpoint تبدیل گفتار به متن (رونویسی) می‌توانید فایل صوتی یا ویدیویی را به متن تبدیل کنید. این endpoint با audio.transcriptions در SDKهای OpenAI سازگار است و فارسی را به خوبی پشتیبانی می‌کند.

POST https://hooshvana.ir/api/v1/audio/transcriptions

برخلاف بیشتر endpointها، بدنه‌ی این درخواست JSON نیست و به صورت multipart/form-data ارسال می‌شود، چون شامل فایل است.

پارامترها

هر دو مدل openai/whisper-1 و openai/gpt-transcribe خروجی json و text می‌دهند.

قالب و حجم فایل

• قالب‌های رایج پذیرفته می‌شوند: mp3، mp4، mpeg، mpga، m4a، wav، webm و ogg.
• حداکثر حجم هر فایل ۲۵ مگابایت است. فایل بزرگ‌تر با خطای invalid_request رد می‌شود.

چرا language را تعیین کنیم؟

مدل‌ها زبان را خودشان هم تشخیص می‌دهند، ولی تعیین صریح "language": "fa" دقت را بالا می‌برد، به‌خصوص وقتی صدا کوتاه است یا کلمات انگلیسی زیادی در گفتار وجود دارد. بدون آن، ممکن است بخشی از گفتار فارسی با الفبای لاتین یا به زبان دیگری نوشته شود.

درخواست با cURL

curl https://hooshvana.ir/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY" \
  -F file=@meeting.m4a \
  -F model=openai/whisper-1 \
  -F language=fa \
  -F response_format=json

پاسخ:

{
  "text": "سلام، جلسه را با مرور گزارش فروش ماه گذشته شروع می‌کنیم."
}

هدر Content-Type را دستی تنظیم نکنید. cURL با گزینه‌ی -F آن را همراه با boundary درست می‌سازد.

Python

import os
from openai import OpenAI

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

with open("interview.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(
        model="openai/gpt-transcribe",
        file=audio,
        language="fa",
        prompt="هوشوانا، API، پایتون",
    )

print(transcript.text)

زیرنویس

خروجی زیرنویس با زمان‌بندی (srt و vtt) فعلاً پشتیبانی نمی‌شود. متن کامل را با json یا text بگیرید و با ابزار زیرنویس‌سازی خودتان زمان‌بندی کنید.

قالب verbose_json در صورت وجود، مدت فایل و بخش‌بندی (segments) را هم برمی‌گرداند؛ این اطلاعات به مدل بستگی دارد.

Node.js

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

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

const transcript = await client.audio.transcriptions.create({
  model: "openai/whisper-1",
  file: fs.createReadStream("voice-note.ogg"),
  language: "fa",
});

console.log(transcript.text);

فایل‌های بزرگ‌تر از ۲۵ مگابایت

دو راه دارید:

1. فشرده‌سازی: گفتار به کیفیت بالا نیاز ندارد. تبدیل به mp3 تک‌کاناله با نرخ بیت پایین معمولاً حجم را چند برابر کم می‌کند:

ffmpeg -i long-meeting.wav -ac 1 -ar 16000 -b:a 48k long-meeting.mp3

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

ffmpeg -i long-meeting.mp3 -f segment -segment_time 600 -c copy part_%03d.mp3

نکته‌هایی برای دقت بیشتر در فارسی

• صدای تمیز با نویز کم بهترین نتیجه را می‌دهد. اگر می‌توانید، میکروفون را به گوینده نزدیک کنید.
• اسم‌های خاص، نام برندها و اصطلاحات تخصصی را در prompt بیاورید.
• خروجی را در صورت نیاز با یک مدل چت ویرایش کنید (اصلاح نیم‌فاصله‌ها، علائم نگارشی یا تبدیل گفتار محاوره‌ای به نوشتار).

هزینه

هزینه‌ی رونویسی به ازای هر دقیقه‌ی صدا محاسبه می‌شود و به مدل بستگی دارد. مثلاً یک فایل ۱۰ دقیقه‌ای، ده برابر قیمت دقیقه‌ی آن مدل هزینه دارد. حذف سکوت‌های طولانی از ابتدا و انتهای فایل هزینه را کم می‌کند. قیمت هر مدل را در صفحه‌ی قیمت‌ها ببینید.