فيديو HeyGen Avatar من نص، بما فيه API v3

فيديو HeyGen Avatar هو نص وصوت وشكل ينطق الكلمات. يمكنك بناء ذلك في AI Studio لمقدمة دورة، أو إرسال نفس الثلاثة أجزاء إلى POST /v3/videos. الترجمة تدبيج الكلام. لا تعيد كتابة الكلمات المرسومة في الإطار. تستخدم هذه المختبرة مركز المساعدة وتوثيق v3 كما تُقرأ في أكتوبر 2026.

اكتب النص في AI Studio

تقول مقالة نص AI Studio أن كل مشهد له نصه الخاص. Add Scene، ثم اختر Blank أو From Template، واكتب في محرر النص. عين صورة وصوت وخلفية بعد وجود الكلمات. النص ما يقوله الصورة. إنه ليس مسار تسمية توضيحية ما لم تضيف تسميات توضيحية بشكل منفصل.

تقول نفس المقالة أنه يمكنك تنزيل أو تحميل النص الكامل من القائمة العلوية اليسرى، بما فيه مواضع التوقف. الملف يُقرأ في المتصفح وليس تحميله كملف النص نفسه. الحدود الموضحة هناك:

• سطر أو فقرة أو خلية تزيد عن 1000 حرف يتم تقسيمها إلى أكثر من مقطع واحد.
• يخطط المقطع الواحد إلى مشهد واحد، بالترتيب. تنشئ المقاطع الإضافية مشاهد إضافية.
• يتم تخطي الأسطر الفارغة والخلايا الفارغة.
• إذا كان الفيديو بالفعل يحتوي على نص، يضيف التحميل مشاهد. لا يستبدل ما هو موجود.
• إذا حددت عدة ملفات، يتم استخدام الملف الأول فقط.
• .doc غير مقبول. احفظ ملفات Word كـ .docx.
• بالنسبة لـ .txt، ضع كل مشهد في سطره الخاص. لـ Excel أو CSV، ضع كل مشهد في خليته الخاصة.

لمقدمة دورة، اكتب جملة واحدة لكل مشهد. المشهد الأول هو الوعد (“هذا الدرس يصحح ImagePullBackOff”). المشهد الثاني هو الأمر الذي سيقوم به المشاهد. المشهد الثالث هو حيث الخطوات المكتوبة تعيش على موقعك. المشاهد القصيرة أسهل في الاستبدال عند تغيير الراية.

النطق من أسماء المنتجات هو مشكلة مسرد، لا مشكلة تهجئة. تشير مقالة النص إلى إصلاح النطق في المحرر. قسم Brand Glossary أدناه هو الإصدار الدائم من هذا الإصلاح.

صور وأصوات

في المنتج، نظام Brand System له علامة تبويب Avatars. Add Brand Avatar يختار المظهر الذي ينتمي إلى تلك العلامة التجارية، لذا فإن سلسلة درس لا تنجرف عبر الوجوه الأساسية.

في API، يمكن avatar_id أن يكون صورة avatar أو مظهر صورة avatar. يقول مرجع create-video إن الأنواع هي studio avatar و digital twin و photo avatar. إذا حذفت engine، يستخدم الخادم Avatar IV. ضع engine.type إلى avatar_v فقط عندما تعني Avatar V. تقول صفحة التسعير Enterprise إن Avatar V مخصص للتوائم الرقمية. لا ترسل Avatar V لمظهر يقول المرجع يتم رفضه. avatars الصور يمكن أن تأخذ motion_prompt على أي محرك. avatars الفيديو تأخذ motion_prompt عندما يكون المحرك Avatar V. يقول المرجع Avatar IV يرفض أن المطالبة لـ avatars الفيديو.

expressiveness (high, medium, low) هو avatars الصور على Avatar IV فقط. إنه يفترض منخفض عند حذفه، وهو مرفوض لـ Avatar V.

الأصوات معرفات وليست أسماء العرض. GET /v3/voices اسردها. تقول صفحة حدود الاستخدام أن تلك القائمة افتراضياً 20 وتحد صفحة في 100. GET /v3/avatars افتراضياً 20 وتحد في 50. كلاهما يستخدم limit و next_token.

البدء السريع يسمي أيضاً مسارات استنساخ اثنين في المنتج: صوت فوري من تسجيل واحد، واستنساخ احترافي مدرب على 20 دقيقة أو أكثر من الصوت. مرر voice_id الناتج في استدعاء الفيديو. voice_settings اختيارية في الإنشاء تشمل speed و pitch و volume و locale.

يمكنك تخطي التوليف وتمرير audio_url أو audio_asset_id بدلاً من script. هاتان الاثنتان متنافيتان مع السماح للنص بتشغيل الصوت. يجب أن يكون URL الذي تمرره علناً. تقول ملاحظة استكشاف الأخطاء في البدء السريع إن 400 download_failed يعني أن URL لم يتمكن من جلبها.

نظام Brand والمسرد

تسمي مقالة المساعدة هذا نظام Brand، وليس مجموعة فضفاضة من التحميلات. علامات التبويب:

• Brand Spec: الألوان (بما فيها قيمة hex) والخطوط لـ Body و Caption و Display و Heading و Heading 2.
• Assets: صور ومقاطع فيديو، عبر Upload Brand Assets.
• Logos: Upload Brand Logos.
• Motion: قطع الحركة المحفوظة من Video Agent.
• Avatars: Add Brand Avatar.

حدود التحميل على تلك المقالة، اعتباراً من الصفحة المقروءة في أكتوبر 2026: الدقة حتى 4096 بـ 4096. صور وشعارات JPG أو PNG حتى 200 ميجا بايت (كما تنص على 4167 بـ 4167). MP4 أو MOV حتى 200 ميجا بايت. خطوط TTF أو OTF حتى 100 ميجا بايت.

تطبق نظام Brand من AI Studio مع Brand في القائمة اليمنى، أو من Video Agent بواسطة + التحكم بجانب المطالبة، ثم Brand System.

Brand Glossary هو النصف الثاني من العلامات التجارية. افتح Brand في الملاحة اليسرى، ثم Brand Glossary.

• قواعس النطق تؤثر على text-to-speech في AI Studio. تقول المقالة تلك الكلمات تظهر في أرجواني مائل في محرر النص.
• قواعس الترجمة هي Force Translate (استخدم هذه الصيغة) أو Don’t Translate (اترك المصطلح). تنطبق عند تشغيل ترجمة فيديو مع تحديد المسرد.

في API، brand_glossary_id يغير كيفية تحدث script. يقول المرجع أن audio_url أو audio_asset_id المزود لا تعاد كتابته بواسطة المسرد. التسميات التوضيحية لا تزال تظهر كلمات النص الأصلية. النطق هو الصوت فقط. اكتشف معرفات مع GET /v3/brand-glossaries.

folder_id ليس مجموعة علامات تجارية. يقول المرجع أن معرف مشروع مجموعة علامات تجارية يتم رفضه مع 404 قبل إنشاء أي شيء. حذف folder_id، أو مرر معرف مجلد حقيقي من POST /v3/folders.

الترجمة والدبيج

ترجمة الفيديو، في مقالة المساعدة، تعيد صياغة المسار المنطوق بلغة أخرى، باستخدام صوت المتحدث الأصلي، وتستطيع مزامنة الشفاه. تحمل فيديو، واختر لغات مستهدفة وآلية ترجمة، وقم بـ Translate.

ما يتحرك:

• الصوت المنطوق، بصوت المتحدث الأصلي.
• حركة الشفاه، إذا قمت بتشغيل ذلك.
• التسميات التوضيحية على الشاشة، إذا قمت بتشغيل تلك.

ما يبقى:

• النص الذي جزء من الصورة: عناوين وأسفل الشاشة والتسميات التوضيحية المشفرة بقوة.
• موسيقى الخلفية، ما لم تقم بتفعيل Remove Background Sound.

الغناء ومقاطع الفيديو الموجهة للموسيقى تُستدعى غير متسقة. لا تدعم لغات المصدر غير المدعومة وتفشل على الفور وتقول المقالة إنها لا تستخدم أرصدة. إذا كنت تحتاج الكلمات على الشاشة بلغة جديدة، بناء ذلك الفيديو في الاستوديو. لا تتوقع من الترجمة إعادة رسم البكسل.

نقطة النهاية القائمة على API GET /v3/video-translations موجودة على صفحة حدود الاستخدام (حجم صفحة افتراضية 10، حد أقصى 100). لا تظهر هذه المختبرة جسم ترجمة POST لأن مخطط الطلب هذا لم يكن على الصفحات المقروءة هنا. تقول مقالة المساعدة أن API يمكن أن يشغل الترجمة. ابحث عن استدعاء الإنشاء الحالي في توثيق المطورين قبل أتمتتها.

استخدام API يتم فاتورته بشكل منفصل عن خطط التطبيق. تقول مقالة مساعدة تسعير API أن أرصدة API تُدفع كما تذهب وليست نفس المحفظة مثل اشتراك Creator أو Pro أو Business. لا تنسخ هذه المختبرة معدلات كل ثانية. تستخدم الصفحة ذاتية الخدمة وصفحة Enterprise وحدات مختلفة.

إنتاج فيديو من API

عنوان URL الأساسي https://api.heygen.com. أنشئ مفتاح في صفحة مفاتيح API وصدره بنفسك. يتحقق البدء السريع من المفتاح مع GET /v3/users/me. 401 يعني أن الرأس مفقود أو المفتاح غير نشط.

export HEYGEN_API_KEY="your-key"

اسرد مظهر وصوت، ثم أنشئ. يكتب البدء السريع الرأس كـ X-Api-Key. يكتب المرجع REST x-api-key. أسماء رؤوس HTTP غير حساسة لحالة الأحرف. استخدم واحد منهما، وليس مفتاح سلسلة الاستعلام.

curl "https://api.heygen.com/v3/avatars?limit=20" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

curl "https://api.heygen.com/v3/voices?limit=20" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c0b2e-7a11-4d5e-9c31-2b6a8e0d11ab" \
  -d "{\"type\":\"avatar\",\"avatar_id\":\"YOUR_AVATAR_ID\",\"voice_id\":\"YOUR_VOICE_ID\",\"script\":\"This lesson shows how to read a CrashLoopBackOff event before you change the image.\",\"title\":\"CrashLoop lesson intro\",\"aspect_ratio\":\"16:9\"}"

يتضمن جسم الاستجابة video_id و status. الحالة القياسية مثال هي waiting. Idempotency-Key من 1 إلى 255 حرف من الأحرف والأرقام و _:.- يجعل إعادة محاولة خلال النافذة الموثقة تعود الاستجابة الأصلية بدلاً من التقديم الثاني. لا تزال نسخة مكررة قيد الطيران تعود 409.

استقصيء حتى ينتهي المهمة:

curl "https://api.heygen.com/v3/videos/VIDEO_ID" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

يتعامل البدء السريع مع completed و failed كحالات نهائية لـ GET /v3/videos/{video_id} ويقرأ video_url من تلك الحمولة. عند الفشل، اقرأ failure_code و failure_message. 429 يعني أنك ضربت حد معدل أو تزامن. احترم Retry-After والعودة. يمكنك أيضاً تمرير callback_url على الإنشاء وتخطي حلقة الاستقصاء.

قيود الإخراج من صفحة حدود الاستخدام: فيديو avatar هو 25 إطار في الثانية. يجب أن تجلس العرض والارتفاع كل منهما بين 128 و 4096 بكسل. الإخراج الافتراضي هو 1080p. قيم aspect_ratio في مرجع الإنشاء تشمل 16:9 (الافتراضي) و 9:16 و 4:5 و 5:4 و 1:1 و auto. مشهد أطول من 30 دقيقة يفشل أثناء التقديم. طلب avatar هو مشهد واحد، لذا 30 دقيقة هي الفيديو بأكمله. مقاطع الفيديو الاستوديو والقالب متعدد المشاهد يمكن أن تعمل أطول، طالما كل مشهد يبقى تحت ذلك الحد. الصفحة أيضاً تحد المشاهد في 50. 4k في مرجع الإنشاء مخصص لـ Avatar III digital twins وstudio avatars وليس مفتاح عام.

output_format افتراضياً mp4. يمكن لـ caption الاختيارية أن تطلب ملف srt. background الاختيارية تأخذ قيمة لون أو عنوان URL أو معرف الأصل.

مسارات إنشاء اثنتان أخرى موجودتان وليست استدعاء النص-إلى-صورة:

• POST /v3/video-agents تأخذ prompt. استقصيء البدء السريع الجلسة لـ video_id ثم استقصيء الفيديو. هذا هو Video Agent: الخدمة تصيغ الجزء.
• POST /v3/models/videos مع نموذج heygen-video-1 يولد مشهد من مطالبة (نص أو صورة أو مرجع). تقول صفحة النموذج أن هذا أداة مختلفة عن محركات avatar وراء POST /v3/videos.

استخدم /v3/videos عندما تكتب بالفعل الكلمات. يقول البدء السريع أن v1 و v2 تبقى مدعومة حتى 31 أكتوبر 2026. الكود الجديد يجب أن يكون v3.

يمكن لأداة سير العمل POST هذه الحمولة والاستقصاء. نمط للاستدعاء الناجم عن webhook HTTP موجود في أول سير عمل n8n. وكيل يقرر متى تقديم تصميم مختلف. انظر ما هو ذكاء اصطناعي agentive.

مقدمات الدورة والدروس القصيرة

استخدم صورة intro عندما يكون الدرس رأس متحدث بالإضافة إلى تسجيل شاشة لاحق تحرره بنفسك. HeyGen مكان سيء لإظهار محطة طرفية مباشرة. سجل المحطة الطرفية بشكل منفصل، واترك الصورة تتعامل مع 20 إلى 40 ثانية من الإطار.

احفظ kubectl واسم الصورة وتهجئات العلم في Brand Glossary بحيث لا يخترع الصوت النطق. ضع الأمر المكتوب على الشاشة في المحرر إذا كان يجب على الطلاب قراءته. الترجمة لن تحول ذلك الطبقة الزائدة.

للسلسلة، أقفل صورة واحدة وصوت واحد ونظام Brand واحد و 16:9. انتقل إلى 9:16 فقط للقطع، كتقديم ثاني، وليس بقص الدرس في أداة خارجية والأمل في أن الفم لا يزال يطابق.

يمكن أن يبدأ البحث للنص في Perplexity. الصيغة المنطوقة لا تزال تحتاج إلى مطابقة الوثيقة التي فتحتها. تمرير Gemini على الخطوط العريضة اختياري. ورقة الغش أدوات Gemini هي جانب API ذلك، وليس معرج فيديو.

قائمة التحقق من الجودة

• اقرأ النص بصوت عال. فكرة واحدة لكل مشهد. قسّم أي شيء المستورد سيكسره في 1000 حرف.
• تأكد من avatar_id و voice_id من نقاط النهاية القائمة، وليس من لقطة شاشة.
• ضع aspect_ratio إلى لاعب تشحنه (16:9 لصفحة دورة).
• أضف قواعس مسرد لأسماء المنتجات وأدوات CLI قبل أن تقدم دفعة.
• لا تخبز عنوان الدرس في البكسل إذا كنت ستترجم. أضف تسميات توضيحية كتسميات توضيحية.
• انتظر completed. جسم waiting أو جاري لا له ملف نهائي.
• قم بتشغيل mp4 بالصوت. تحقق من أول خمس ثوان من حركة الفم وأي كلمة أضفتها إلى المسرد.
• عند failed، انسخ failure_code و failure_message قبل إعادة المحاولة. غير مفتاح idempotency فقط عندما تقصد فيديو جديد.
• عند 401، أصلح المفتاح. عند 429، انتظر Retry-After. عند 400 download_failed، عنوان URL الصوت أو الخلفية ليس قابلاً للجلب علناً.
• احفظ المفتاح خارج repo. توثيق البدء السريع الخاص بالوكيل تقول لتصديرها محلياً وليس لصقها في دردشة.

الأسئلة الشائعة

أي نقطة نهاية HeyGen API تُنشئ فيديو avatar من نص؟

POST https://api.heygen.com/v3/videos مع نوع JSON avatar، بالإضافة إلى avatar_id و script و voice_id. الرأس هو X-Api-Key. تعود استدعاء الإنشاء video_id والحالة مثل waiting. استقصيء GET /v3/videos/{video_id} حتى تكون الحالة completed أو failed. تبقى v1 و v2 مدعومة حتى 31 أكتوبر 2026، وفقاً للبدء السريع المقروء في أكتوبر 2026.

هل ترجمة فيديو HeyGen تعيد كتابة النص على الشاشة؟

لا. تقول مقالة مساعدة ترجمة الفيديو إن الصوت المنطوق يُعاد صياغته، وحركة الشفاه والتسميات التوضيحية على الشاشة اختيارية. النص المخبأ في الصورة والرسومات والتسميات التوضيحية المشفرة بقوة تبقى كما هي. موسيقى الخلفية تبقى ما لم تقم بتفعيل Remove Background Sound. الكلمات المغناة ليست حالة موثوقة.

ما هو نظام HeyGen Brand؟

إنه اسم مركز المساعدة الحالي لمجموعة العلامات التجارية: الألوان والخطوط والشعارات والصور والعناصر الحركية والصور المختارة. Brand Glossary منفصل. إنه يحتفظ بقواعس النطق لـ AI Studio speech وقواعس الترجمة (Force Translate أو Don’t Translate) المستخدمة عند تشغيل ترجمة فيديو مع تحديد المسرد.

لماذا عاد POST /v3/videos بـ 404 لمجلدي؟

يقول مرجع create-video إن folder_id يجب أن يكون مجلداً يمكن للمتصل الكتابة إليه وليس في سلة المحذوفات. معرف من مساحة عمل أخرى أو مشروع من نوع آخر مثل مجموعة علامات تجارية يتم رفضه بـ 404 قبل إنشاء فيديو. اسرد avatars مع GET /v3/avatars والأصوات مع GET /v3/voices بدلاً من لصق معرف مجموعة العلامات التجارية في folder_id.