مستندات APIمسیرهاDubbing

دوبله صوت و ویدیو (Dubbing)

صوت یا ویدیو را با حفظ صدای گوینده‌ها به زبان دیگری دوبله کنید؛ مثلاً ویدیوی انگلیسی به فارسی. تسک ناهمگام است و نتیجه را از مسیر پیگیری تسک می‌گیرید.

نسخهٔ API: v1

مسیر درخواست

POSThttps://bananaai.ir/api/v1/audio/dubbing

گفتار یک فایل صوتی یا ویدیویی را ترجمه و با صدای همان گوینده‌ها به زبان مقصد بازخوانی می‌کند. مثل تولید ویدیو یک تسک ناهمگام می‌سازد؛ دوبله معمولاً یک تا چند دقیقه طول می‌کشد. اگر ورودی ویدیو باشد، خروجی همان ویدیو با صدای دوبله‌شده است؛ اگر صوت باشد، خروجی فایل صوتی است.

پارامترهای درخواست

بدنهٔ درخواست باید JSON باشد (Content-Type: application/json).

source_urlstringالزامی: نشانی عمومی https فایل صوتی یا ویدیویی (MP3، WAV، M4A، OGG، WEBM، MP4 یا MOV)؛ حداکثر ۵ دقیقه و ۱۰۰ مگابایت. صوتی یا ویدیویی بودن خودکار تشخیص داده می‌شود.; مثال:https://example.com/intro-en.mp4
target_languagestringالزامی: زبان مقصد دوبله.; مقادیر مجاز:faenartrdefresitptrujakozhhinlplsvidukroelcsdafibghrskmsfilta
source_languagestringاختیاری: زبان گفتار فایل ورودی. با auto خودکار تشخیص داده می‌شود. نباید با زبان مقصد یکی باشد.; پیش‌فرض:autoمقادیر مجاز:autofaenartrdefresitptrujakozhhinlplsvidukroelcsdafibghrskmsfilta
metadataobjectاختیاری: جفت‌های کلید/مقدار دلخواه (تا ۱۶ کلید، مقدار حداکثر ۵۰۰ کاراکتر) مثل شناسهٔ سفارش شما. در پاسخ تسک و بدنهٔ وب‌هوک عیناً برمی‌گردد تا نتیجه را به رکورد خودتان وصل کنید.; مثال:{"order_id":"1042"}

هزینه

به ازای هر دقیقهٔ فایل ورودی (رو به بالا، حداقل ۱ دقیقه)؛ مدت فایل را خودمان اندازه می‌گیریم. مبلغ هنگام ثبت رزرو و فقط پس از دوبلهٔ موفق کسر می‌شود. جزئیات در اعتبار و هزینه.

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

bash

curl -X POST "https://bananaai.ir/api/v1/audio/dubbing" \
  -H "Authorization: Bearer ba_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "source_url": "https://example.com/intro-en.mp4",
  "target_language": "fa",
  "source_language": "en",
  "metadata": {
    "video_id": "42"
  }
}'

پاسخ

JSON

1{
2  "id": "dub_8f2a1c::lang_3b9e7d",
3  "status": "pending",
4  "type": "video",
5  "model": "elevenlabs-dubbing:fa",
6  "target_language": "fa",
7  "source_language": "en",
8  "duration_seconds": 47.3,
9  "credits_reserved": 90,
10  "metadata": { "video_id": "42" },
11  "created_at": "2026-09-29T12:00:00.000Z"
12}

شناسهٔ تسک در فیلد id است و ممکن است :: داشته باشد؛ هنگام ساختن نشانی پیگیری آن را با encodeURIComponent رمزگذاری کنید.

دریافت نتیجه

وضعیت را هر ۵ تا ۱۰ ثانیه از GET /api/v1/tasks/:id بخوانید، یا وب‌هوک task.completed را فعال کنید. پس از completed، خروجی ویدیویی در videos و خروجی صوتی در audios است:

JSON

1{
2  "id": "dub_8f2a1c::lang_3b9e7d",
3  "status": "completed",
4  "type": "video",
5  "model": "elevenlabs-dubbing:fa",
6  "prompt": "دوبلاژ به فارسی (fa)",
7  "images": [],
8  "videos": ["https://cdn.bananaai.ir/.../dubbed-fa.mp4"],
9  "audios": [],
10  "error": null,
11  "credits_reserved": 90,
12  "credits_deducted": true,
13  "metadata": { "video_id": "42" },
14  "created_at": "2026-09-29T12:00:00.000Z",
15  "completed_at": "2026-09-29T12:02:41.000Z"
16}

نکته

برای ویدیوهای طولانی‌تر از ۵ دقیقه، فایل را به چند بخش تقسیم کنید و هر بخش را جداگانه دوبله کنید.