با ۵ خط کد، گفتار فارسی بساز

مدل و صدا را انتخاب کن — کد آماده را بگیر. پاسخ، خودِ فایل MP3 است.

⚡ پاسخ مستقیم MP3 📄 MP3 ۶۴k مونو 🟢 مجوز MIT ‏(pocket)

سازندهٔ درخواست

مدل و صدا را انتخاب کن؛ کد زیر همان لحظه عوض می‌شود.

مدل:

صدا:

terminal

کلید بگیر: دکمهٔ «ورود» بالای صفحهٔ اصلی ← تب «کلید API» ← «ساخت کلید». کلید فقط یک بار نمایش داده می‌شود — همان لحظه کپی کن.

کد بالا را اجرا کن.

sample.mp3 را پخش کن. تمام — این کل API است.

استفاده در Python و Node

Python

Node.js 18+

curl — omnivoice با جنسیت صریح (مرجع)

# omnivoice: CC-BY-NC — personal / non-commercial ONLY
# instruct whitelist: female / male / whisper / elderly / child / ...
curl -X POST https://farsihoosh.ir/api/tts \
  -H "Authorization: Bearer fh_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"سلام این یک آزمایش است","model":"omnivoice","instruct":"female"}' \
  --output sample.mp3

مدل‌ها و قانون جنسیت

omnivoiceزن و مرد

صفحهٔ مدلhuggingface.co/Serveurperso/OmniVoice-GGUF

صداهازن و مرد (لیست مجاز)

پارامتر جنسیتاختیاری — "instruct":"female" یا "male"؛ پیش‌فرض زن

pocketتک‌صدا (زن)

صفحهٔ مدلhuggingface.co/mehdi-hf/pocket-tts-farsi

صداهافقط زن (یک صدای ثابت)

پارامتر جنسیتنفرستید. اگر بفرستید — حتی "male" — سرویس آن را نادیده می‌گیرد و همیشه همان صدای پیش‌فرض (زن) را می‌سازد. خطا نمی‌دهیم؛ صدا عوض نمی‌شود.

pocket-v2دو صدا (زن و مرد)

صفحهٔ مدلhuggingface.co/mehdi-hf/pocket-tts-farsi-v2

صداهازن و مرد (دو پرامپت صوتی)

پارامتر صدا"instruct":"female" یا "male"؛ پیش‌فرض زن.

مجوزCC-BY-NC-4.0 — فقط غیرتجاری (ذکر منبع: لینک همین صفحهٔ مدل).

چرا pocket جنسیت ندارد؟ این مدل با یک صدای زنِ ثابت آموزش دیده (مجوز MIT، سریع‌ترین موتور ما). درخواست با instruct برای pocket نه خطا می‌دهد نه صدا را عوض می‌کند — همیشه زن است. برای صدای مرد از omnivoice استفاده کنید (فقط غیرتجاری).

پارامترها

فیلد	الزام	توضیح
`text`	الزامی	متن فارسی، ۱۰ تا ۱۵۰۰ کاراکتر
`model`	اختیاری	`omnivoice` (پیش‌فرض) یا `pocket` یا `pocket-v2`
`instruct`	اختیاری	برای omnivoice و pocket-v2 — توصیف صدا از لیست مجاز. برای pocket نادیده گرفته می‌شود (همیشه زن). (برای pocket-v2 فقط `female` یا `male`).
`seed`	اختیاری	فقط omnivoice — اگر نفرستید مثل سایت می‌شود (زن 777 / مرد 8888)؛ برای pocket و pocket-v2 نادیده گرفته می‌شود

محدودیت‌ها

چی	چقدر
کاراکتر روزانهٔ هر کلید	۲۰۰٬۰۰۰ — ریست با UTC، بعدش 429 + `Retry-After`
سرعت هر کلید و هر IP	۱۰ درخواست در دقیقه
طول متن	۱۰ تا ۱۵۰۰ کاراکتر

خطاها — کامل

401auth_required

چراسربرگ Authorization نبود

چیکار کنمBearer + کلید را بفرست

401bad_auth_scheme

چراسربرگ Authorization هست ولی Bearer ندارد

چیکار کنمدقیقاً بنویس Authorization: Bearer fh_live_… (کلمهٔ Bearer + فاصله)

401bad_key

چراکلید نادرست

چیکار کنمکلید را کامل و بدون فاصله بفرست

401revoked_key

چراکلید باطل شده

چیکار کنمکلید جدید بساز

403key_owner_mismatch

چراکلیدی که فرستادی مال حساب دیگری است و در این مرورگر با حساب دیگری وارد شده‌ای

چیکار کنمکلید حساب خودت را بساز و همان را بفرست؛ یا از حساب درست خارج شو. کلاینت‌های سروری بدون نشست مرورگر (فقط Bearer) این خطا را نمی‌گیرند.

422invalid_body

چراJSON خراب / آرایه به‌جای آبجکت

چیکار کنمContent-Type: application/json + آبجکت JSON

422text is required…

چرامتن خالی

چیکار کنمtext را بفرست

422«حداقل ۱۰ حرف»

چرامتن خیلی کوتاه

چیکار کنم۱۰+ کاراکتر بفرست

422limit is 1500

چرامتن خیلی بلند

چیکار کنمقطعه‌قطعه بفرست

422unsupported model

چرامدل ناموجود

چیکار کنمomnivoice یا pocket یا pocket-v2

429X-RateLimit-Scope: key_burst

چراهر کلید ۱۰ درخواست در یک دقیقه

چیکار کنمRetry-After: 60 ثانیه

429X-RateLimit-Scope: key_daily

چرا۲۰۰K کاراکتر روزانه پر شد

چیکار کنمتا ریست UTC — Retry-After می‌گوید چند ثانیه

429X-RateLimit-Scope: burst|daily

چراسطل IP

چیکار کنمکندتر بفرست

429X-RateLimit-Scope: almas_empty

چراموجودی الماس حساب برای مدل‌های هزینه‌دار صفر یا کمتر است، یا برای همین درخواست کافی نیست (مثلاً ۱٬۰۰۰ الماس برای یک تصویر ۷٬۵۰۰ الماسی)؛ خرید بستهٔ درخواست این موجودی را شارژ نمی‌کند. برای استخراج متن (OCR) یک حداقل ۱۰٬۰۰۰ الماس هم لازم است، چون قیمت OCR بر اساس طول متن خروجی است و پیش از اجرا معلوم نیست

هدرهاX-Almas-Left موجودی فعلی (کف صفر)؛ X-Almas-Needed مبلغ لازم برای همین درخواست؛ و در حالت «کمتر از حداقل OCR» X-Almas-Min = همان حداقل (۱۰٬۰۰۰)؛ بدون Retry-After (انتظار کیف پول را شارژ نمی‌کند)

چیکار کنمشارژ حساب الماس از /upgrade#شارژ-حساب (۱۰۰٬۰۰۰ تومان → ۱۰۰٬۰۰۰ الماس · ۱٬۰۰۰٬۰۰۰ تومان → ۱٬۰۰۰٬۰۰۰ الماس)؛ مدل‌های رایگان همچنان سرو می‌شوند

503worker unreachable

چراموتور omni قطع

چیکار کنمبعداً تلاش کن (Retry-After: 5)

503X-RateLimit-Scope: caller_busy

چرااز یک IP بیش از حد درخواست هم‌زمان فرستادی (۸ درخواست هم‌زمان؛ برای کاربر ناشناس ۴)

چیکار کنمکمی صبر کن و دوباره بفرست (Retry-After: 3) — این خطا یعنی صف شلوغ نیست، فقط درخواست‌های هم‌زمانِ تو زیاد بوده