Text to Speech

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

POST /v1/audio/speech

درخواست با application/json ارسال می‌شود. گدارAI مدل را اعتبارسنجی می‌کند، مسیر مناسب ارائه‌دهنده را پیدا می‌کند، مقدار model را برای ارائه‌دهنده بازنویسی می‌کند و خروجی صوتی را بدون ثبت متن خام یا صوت خام عبور می‌دهد.

اطلاع

این مسیر برای providerهایی فعال است که قرارداد OpenAI-compatible audio/speech را ارائه می‌کنند؛ مانند openai و providerهای سازگار که در حساب ارائه‌دهنده شما فعال شده‌اند. APIهای بومی مثل سرویس‌های Speech مستقل گوگل، AWS یا Azure قرارداد متفاوتی دارند و فقط بعد از اضافه‌شدن adapter اختصاصی از همین endpoint پشتیبانی می‌شوند.

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

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

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

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

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

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

Python

import requests

response = requests.post(
  "https://YOUR_WORKSPACE.godarai.ir/v1/audio/speech",
  headers={
      "Authorization": "Bearer YOUR_GODARAI_TOKEN",
      "Content-Type": "application/json",
  },
  json={
      "model": "openai:default:gpt-4o-mini-tts",
      "voice": "alloy",
      "input": "سلام، به راهنمای گدارAI خوش آمدید.",
      "response_format": "mp3",
  },
  timeout=120,
)

response.raise_for_status()
with open("welcome.mp3", "wb") as audio_file:
  audio_file.write(response.content)

NodeJS

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

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/audio/speech", {
method: "POST",
headers: {
  Authorization: "Bearer YOUR_GODARAI_TOKEN",
  "Content-Type": "application/json",
},
body: JSON.stringify({
  model: "openai:default:gpt-4o-mini-tts",
  voice: "alloy",
  input: "سلام، به راهنمای گدارAI خوش آمدید.",
  response_format: "mp3",
}),
});

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

await writeFile("welcome.mp3", Buffer.from(await response.arrayBuffer()));

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/audio/speech" --header "Authorization: Bearer YOUR_GODARAI_TOKEN" --header "Content-Type: application/json" --output welcome.mp3 --data '{
  "model": "openai:default:gpt-4o-mini-tts",
  "voice": "alloy",
  "input": "سلام، به راهنمای گدارAI خوش آمدید.",
  "response_format": "mp3"
}'

OpenAI Python SDK

from openai import OpenAI

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

audio = client.audio.speech.create(
  model="openai:default:gpt-4o-mini-tts",
  voice="alloy",
  input="سلام، به راهنمای گدارAI خوش آمدید.",
  response_format="mp3",
)

audio.write_to_file("welcome.mp3")

OpenAI NodeJS SDK

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

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

const audio = await client.audio.speech.create({
model: "openai:default:gpt-4o-mini-tts",
voice: "alloy",
input: "سلام، به راهنمای گدارAI خوش آمدید.",
response_format: "mp3",
});

await writeFile("welcome.mp3", Buffer.from(await audio.arrayBuffer()));

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

فیلد	وضعیت	توضیح
model	اجباری	شناسه مدل تولید گفتار مجاز در گدارAI.
input	اجباری	متن ورودی برای خوانده‌شدن. حداکثر طول در قرارداد OpenAI-compatible برابر ۴۰۹۶ کاراکتر است.
voice	اجباری	صدای خروجی. می‌تواند نام صدای آماده مثل alloy باشد یا شیء سفارشی مانند { "id": "voice_1234" }، اگر provider پشتیبانی کند.
response_format	اختیاری	یکی از mp3، opus، aac، flac، wav یا pcm. مقدار پیش‌فرض mp3 است.
speed	اختیاری	سرعت خواندن، عددی بین 0.25 و 4. مقدار پیش‌فرض provider معمولاً 1 است.
instructions	اختیاری	راهنمای کنترل لحن و سبک خواندن، برای مدل‌هایی که آن را پشتیبانی می‌کنند.
stream_format	اختیاری	اگر مقدار sse باشد، پاسخ جریانی text/event-stream از provider عبور داده می‌شود. مقدار audio یا نبودن این فیلد خروجی صوتی عادی می‌دهد.

نکته

برای متن فارسی، کیفیت صدا را با نمونه واقعی محصول خود بسنجید. تلفظ نام برند، عددها، اختصارها و واژه‌های تخصصی می‌تواند بین صداها و مدل‌ها متفاوت باشد.

خروجی

در حالت عادی خروجی فایل صوتی است، نه JSON متنی. گدارAI بدنه و Content-Type موفق provider را حفظ می‌کند؛ برای نمونه audio/mpeg، audio/wav یا فرمت دیگری که provider برگرداند.

سرویس شما می‌تواند خروجی را:

• به کاربر stream کند.
• در storage امن ذخیره کند.
• یا به سیستم پخش صوتی محصول بدهد.

اگر فرمت خروجی برای محصول مهم است، آن را صریح با response_format تنظیم کنید و قبل از انتشار در مرورگرها یا اپلیکیشن‌های هدف آزمایش کنید.

پاسخ جریانی

برای مدل‌هایی که رویدادهای تولید گفتار را پشتیبانی می‌کنند، stream_format را روی sse بگذارید:

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/audio/speech" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai:default:gpt-4o-mini-tts",
    "voice": "alloy",
    "input": "سلام، این پاسخ به شکل جریانی تولید می‌شود.",
    "stream_format": "sse"
  }'

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

نکات عملیاتی

• کلید یا مدل باید اجازه text_to_speech داشته باشد؛ مدل chat، image یا transcription برای این مسیر پذیرفته نمی‌شود.
• متن ورودی خام، instructions خام، شناسه خام صدای سفارشی و صوت خروجی خام در trace و request log ذخیره نمی‌شود؛ فقط طول، hash کوتاه، نوع محتوا و metadata امن ثبت می‌شود.
• میزان مصرف و هزینه بر اساس متن ورودی و usage احتمالی provider ثبت می‌شود. اگر provider فایل صوتی خام بدون usage برگرداند، گدارAI از برآورد اولیه استفاده می‌کند.
• اگر provider خطا بدهد، پیام خطا با قالب OpenAI-compatible به client برمی‌گردد.

طراحی متن ورودی

متنی که برای تولید گفتار می‌فرستید باید خواندنی باشد، نه فقط قابل نمایش:

• جمله‌ها را کوتاه‌تر بنویسید.
• علامت‌گذاری را برای مکث طبیعی رعایت کنید.
• عددها و اختصارهای مهم را در صورت نیاز به شکل خواندنی بنویسید.
• متن خیلی طولانی را به بخش‌های کوتاه‌تر تقسیم کنید.

هشدار

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

تفاوت با Speech to Text

موضوع	Text to Speech	Speech to Text
ورودی	متن	فایل صوتی
خروجی	فایل صوتی	متن
کاربرد	خواندن پاسخ و اعلان صوتی	پیاده‌سازی مکالمه یا پیام صوتی

این دو API در یک محصول می‌توانند کنار هم قرار بگیرند، اما قرارداد و هزینه آن‌ها جداست.

خطاهای رایج

نشانه	علت محتمل	راه‌حل
application/json content type is required	درخواست با فرم یا نوع محتوای اشتباه ارسال شده است.	سرآیند Content-Type: application/json را بفرستید.
model is required	فیلد model در بدنه نیست.	شناسه مدل مجاز فضای کاری را ارسال کنید.
input is required	متن ورودی خالی است یا نوع آن string نیست.	فیلد input را با متن کوتاه و خواندنی بفرستید.
voice is required	صدا مشخص نشده است.	یک صدای سازگار با مدل، مثل alloy، انتخاب کنید.
response_format must be one of...	فرمت خروجی پشتیبانی نمی‌شود.	یکی از mp3، opus، aac، flac، wav یا pcm را انتخاب کنید.
speed must be between 0.25 and 4	سرعت خارج از بازه مجاز است.	مقدار speed را در بازه مجاز تنظیم کنید.
Model access denied or unsupported	مدل برای text_to_speech مجاز نیست.	مدل صوتی مناسب یا مجوز کلید را بررسی کنید.

جمع‌بندی

POST /v1/audio/speech مسیر استاندارد تبدیل متن به صوت در گدارAI است. این مسیر برای providerهای OpenAI-compatible بدنه JSON را عبور می‌دهد، مدل و دسترسی را کنترل می‌کند، خروجی صوتی یا رویدادهای جریانی را برمی‌گرداند و داده حساس متن و صوت را در لاگ خام ذخیره نمی‌کند.