/audio/speech ونتيجة تحويله إلى صوت George. يظهر الشكلان الموجيان على محور زمني واحد، وتقع الفجوات بين العبارات في المواضع نفسها.

/audio/voice-changer/: يحسب عرض السعر سعر مدة معينة، وتُرسل قائمة الانتظار التسجيل وتخصم التكلفة، ويستعلم الاسترجاع دوريًا إلى أن يصبح ملف MP3 جاهزًا، ويحذف الإكمال الوسائط المُخزَّنة بعد حصولك عليها. البنية مماثلة لنقاط نهاية الموسيقى، لكن المسار مختلف، ولا تقبل أيٌّ منهما نماذج الأخرى.
تفترض الأمثلة أن VENICE_API_KEY مُعيَّن:
اختيار نموذج
توجد نماذج تغيير الصوت ضمنGET /models?type=music مع تعيين model_spec.voice_changer على true؛ إذ لا يوجد فلتر نوع مخصّص لها. يوجد حاليًا نموذج واحد هو elevenlabs-voice-changer: يقبل مصادر بصيغ mp3 أو wav أو ogg أو mp4 أو aac حتى 300 ثانية، ويوفّر 20 صوتًا مسمّى مع Aria كصوت افتراضي، ويقبل ElevenLabs Voice ID خامًا بدلًا من الاسم، ويدعم remove_background_noise وseed. قد تتغير هذه التفاصيل، لذا اقرأها من الـ API. يُعيد هذا الاستعلام كل ما يعتمد عليه باقي الدليل:
400. والتسجيل الأطول من max_source_audio_duration_seconds يُعيد 422 قبل أي خصم، مع ذكر الحد في الرسالة.
ثمة أمر واحد لا يتحقق منه الـ API عند وضع الطلب في قائمة الانتظار، وهو اسم الصوت. إذا وضعت في قائمة الانتظار قيمة voice غير موجودة في النموذج، فستحصل مع ذلك على 200 وqueue_id؛ ويصل الرفض عند أول استرجاع، مع استرداد المبلغ المخصوم. تستعيد المال لكنك تخسر رحلة الطلب ذهابًا وإيابًا، لذا تحقق من voices قبل وضع الطلب في قائمة الانتظار.
1. احصل على عرض سعر
تُحتسب الفوترة وفق طول التسجيل المصدر، مقربًا لأعلى إلى الدقيقة الكاملة التالية. بالنسبة إلىelevenlabs-voice-changer، يبلغ ذلك 0.35 دولار لأي مدة حتى 60 ثانية، و0.69 دولار حتى 120، و1.04 دولار حتى 180، و1.38 دولار حتى 240، و1.73 دولار حتى 300. يكلّف مقطع مدته 7 ثوانٍ ما يكلّفه مقطع مدته 60 ثانية، وتُفوتر 60.5 ثانية كدقيقتين. إذا كانت لديك مقاطع قصيرة كثيرة، فادمجها في ملف واحد يبقى دون حدّ الدقيقة بدلًا من وضع كل منها في قائمة الانتظار على حدة. تأتي المستويات من pricing.durations في /models.
يقبل عرض السعر عددًا صحيحًا من الثواني ولا يحتاج إلى مفتاح API:
2. ضع عملية التحويل في قائمة الانتظار
أرسل التسجيل إما كرفعfile عبر multipart أو كـ audio_url في جسم JSON، وليس كليهما. يجب أن يكون عنوان URL قابلًا للوصول علنًا دون ترويسات أو ملفات تعريف ارتباط؛ إذ تجلب Venice البايتات بنفسها ولا تمرّر عنوان URL إلى المزوّد أبدًا. تتحقق Venice من البايتات لا من الامتداد، لذا يجب أن يكون الملف فعلًا إحدى الحاويات المقبولة، وتُرفض الملفات التي تحتوي على مسار فيديو.
عند استخدام curl -F، لا تعيّن Content-Type حتى يتمكن curl من تعيين الحدّ الفاصل لـ multipart، وأرسل remove_background_noise بالقيمة true/false وseed كأرقام.
voice لاستخدام default_voice. عندما تكون قيمة supports_custom_voice_id هي true، يمكن أن يكون voice أيضًا Voice ID من المزوّد؛ وبالنسبة إلى elevenlabs-voice-changer يعني ذلك أي صوت من ElevenLabs يمكنك الوصول إليه، بما في ذلك أصوات المكتبة غير الموجودة في قائمة voices الخاصة بـ Venice. لا يُقبل remove_background_noise وseed إلا عندما يُبلّغ النموذج بدعمهما.
تمنحك الاستجابة المعرّف اللازم لكل ما يلي:
duration_seconds هو الطول الذي قاسته Venice، والمستوى الذي جرت فوترتك عليه. إذا طلبت عرض سعر لـ 60 وكانت هذه القيمة 61.2، فقد دفعت مقابل دقيقتين. احتفظ بـ model وqueue_id؛ فالاسترجاع والإكمال يتطلبانهما، ويظل المعرّف صالحًا لمدة 24 ساعة.
تُخصم التكلفة في هذه المرحلة، لا عند عودة الصوت، لذا لا تُعِد محاولة طلب قائمة الانتظار. إذا كان لديك queue_id، فاستعلم به. وإذا لم تصل الاستجابة أبدًا، فقد يؤدي إرسال التسجيل مرة أخرى إلى خصم التكلفة مرتين. تقتصر قائمة الانتظار على 40 طلبًا في الدقيقة والاسترجاع على 120؛ ويُبلّغ كلاهما عن x-ratelimit-remaining-requests.
3. الاستعلام الدوري والتنزيل
استدعِ الاسترجاع بالقيم المُستلمة من استجابة قائمة الانتظار:audio/mpeg ويكون الجسم هو ملف MP3. فرّع منطقك بناءً على Content-Type.
الرقمان بالميلي ثانية: المدة التي تستغرقها المهام على هذا النموذج عادةً، والمدة التي مضت على تشغيل مهمتك. الفرق بينهما مدة انتظار أولى معقولة، لكن المتوسط مجرد تلميح. فقد استغرق مصدر مدته 148 ثانية 24 ثانية مقابل متوسط قدره 7، لذا في المدخلات الأطول سيتجاوز execution_duration قيمة average_execution_time. عندما يحدث ذلك، انتقل إلى فاصل زمني ثابت من بضع ثوانٍ وتابع. أما المقاطع القصيرة فتسير في الاتجاه المعاكس: فقد عاد مثال الثواني السبع من أول استعلام.
تحمل الاستجابة المكتملة x-venice-audio-duration (بالثواني) وx-venice-inference-time وx-venice-audio-format وx-venice-model-id وx-venice-model-name. يكون الناتج دائمًا MP3 أحادي القناة بمعدل 128 kbps وتردد 44.1 kHz، أيًّا كان ما أرسلته. ينبغي أن تطابق مدة الصوت مصدرك في حدود بضع ميلي ثوانٍ؛ وإذا كان الفرق أكبر من ذلك، فاستمع إليه قبل نشره.
في حال الإخفاق
المهمة التي قبلها المزوّد ثم أخفقت تعود بحالة خطأ معerror وcredits_refunded في الجسم. تعني true أن الخصم قد أُلغي. أما false مع رسالة تنتهي بـ “please contact support” فتعني أن عملية الاسترداد نفسها أخفقت وأن الاستعلام التالي سيحاول مجددًا. النتيجة مُخزَّنة، لذا يعيدها الاستعلام مرة أخرى.
أما المهمة التي لم تصل إلى المزوّد أبدًا فتبدو مختلفة. يستمر الاسترجاع في إعادة PROCESSING لمدة تصل إلى 10 دقائق، ثم يُعيد 504 ويستردّ لك المبلغ، لذا امنح المهمة في حالة PROCESSING تلك المدة على الأقل قبل أن تعدّها عالقة. المجموعة الكاملة من النتائج النهائية موجودة في مرجع الاسترجاع.
التنظيف
مرّرdelete_media_on_completion: true في الاسترجاع لتُحذف الوسائط المُخزَّنة في الاستدعاء نفسه الذي يسلّمك الصوت. وأي استرجاع لاحق لذلك المعرّف يُعيد 404. إذا أردت التنزيل أكثر من مرة، فلا تستخدمه واستدعِ الإكمال عند الانتهاء. يُعيد الإكمال {"success": true} واستدعاؤه آمن لأكثر من مرة.
مثال كامل
كل ما سبق من البداية إلى النهاية: التحقق من وجود الصوت، وطلب عرض السعر، والرفع، والاستعلام الدوري حتى يصل الصوت، ثم حفظه. المهلة 12 دقيقة حتى يظهر إخفاق الإرسال كاسترداد للمبلغ لا كانتهاء للمهلة.delete_media_on_completion واستدعِ الإكمال بنفسك إذا كنت تحتاج إلى الملف أكثر من مرة.