يتوفر Hunyuan Video Fast على Novita AI عبر POST https://api.novita.ai/v3/async/hunyuan-video-fast. وهو النسخة المحسّنة للسرعة من نموذج Tencent مفتوح المصدر Hunyuan Video الأساسي — حيث يقلل وقت التوليد مقارنة بالإصدار القياسي على حساب بعض دقة الحركة، مما يجعله عمليًا لخطوط الإنتاج عالية الإنتاجية، وتكرار تعديل الوصف، وسير عمل المراحل التجريبية حيث تكون سرعة الإنجاز أهم من جودة السينما القصوى.
وكما هو الحال مع جميع واجهات برمجة تطبيقات الفيديو غير المتزامنة في Novita، فإنها تُرجع task_id عند الإرسال وتقدّم رابط الفيديو بمجرد اكتمال المهمة. يغطي هذا الدليل نقطة النهاية، وتنسيق الطلب، وأمثلة عملية بلغة Python و cURL، ومكان استخدام النسخة السريعة مقارنة بالنموذج القياسي.
متى تستخدم Hunyuan Video Fast مقابل الإصدار القياسي
النسخة السريعة هي الخيار الصحيح عندما تكون سرعة الإنجاز وحجم الطلبات أكثر أهمية من جودة الصورة القصوى. ينتج Hunyuan Video القياسي حركة بدقة أعلى والزامًا أفضل بالوصف لكل عملية توليد. أما النسخة السريعة فتقلل ذلك الوقت بشكل ملحوظ — وهي مفيدة من أجل:
- تكرار الوصف — اختبار العديد من الاختلافات بتكلفة منخفضة قبل الالتزام بعرض كامل الجودة
- خطوط الإنتاج عالية الإنتاجية — توليد محتوى بالدفعات حيث يؤثر زمن الانتظار لكل مقطع مباشرة على الإنتاجية
- المراحل التجريبية والمراجعة الداخلية — الحصول على مخرجات قابلة للمشاركة بسرعة، ثم التحول إلى الإصدار القياسي للتسليم النهائي
- التطبيقات منخفضة زمن الاستجابة — سير عمل إنتاجي بميزانيات زمن استجابة صارمة
إذا كانت جودة المخرجات هي القيد الأساسي — البث، أو التسليم النهائي، أو الحركة الواقعية — فاستخدم نقطة نهاية Hunyuan Video القياسية بدلًا من ذلك.
الخطوة 1: احصل على مفتاح API الخاص بك من Novita AI
سجّل في novita.ai وأنشئ مفتاح API من صفحة إدارة المفاتيح. الحسابات الجديدة تحصل على رصيد مجاني. خزّن المفتاح كمتغير بيئة — لا تضعه أبدًا بشكل ثابت داخل ملفات المصدر.
export NOVITA_API_KEY="your_api_key_here"
الخطوة 2: نقطة النهاية ومعرّف النموذج
| الحقل | القيمة |
|---|---|
| نقطة نهاية الإرسال | POST https://api.novita.ai/v3/async/hunyuan-video-fast |
| استرجاع النتيجة | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| ترويسة المصادقة | Authorization: Bearer $NOVITA_API_KEY |
| نوع المحتوى | application/json |
مرجع API الرسمي: novita.ai/docs/api-reference/model-apis-hunyuan-video-fast
الخطوة 3: أرسل طلبك الأول
أرسل طلب توليد مع الوصف وإعدادات المخرجات:
curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
"negative_prompt": "blurry, low quality, distorted, watermark",
"width": 1280,
"height": 720,
"seed": -1
}'
تعيد API قيمة task_id فورًا:
{
"task_id": "hunyuan-fast-abc123"
}
الفيديو ليس في هذا الرد — احفظ task_id واستخدمه في الخطوة التالية.
الخطوة 4: استقصِ نتيجة الفيديو
curl -s "https://api.novita.ai/v3/async/task-result?task_id=hunyuan-fast-abc123" \
-H "Authorization: Bearer $NOVITA_API_KEY"
استمر في الاستقصاء حتى تصبح task_status بقيمة TASK_STATUS_SUCCEED:
{
"task_status": "TASK_STATUS_SUCCEED",
"videos": [
{
"video_url": "https://cdn.novitai.com/output/...",
"video_url_ttl": 3600,
"video_type": "mp4"
}
]
}
نزّل أو خزّن video_url في الوقت المناسب — تنتهي صلاحيته بعد video_url_ttl ثانية.
قيم حالة المهمة
| الحالة | المعنى |
|---|---|
TASK_STATUS_QUEUED |
تم قبول الطلب، بانتظار التنفيذ |
TASK_STATUS_PROCESSING |
جارٍ التوليد |
TASK_STATUS_SUCCEED |
اكتمل — رابط الفيديو متاح في videos[0].video_url |
TASK_STATUS_FAILED |
فشل التوليد — راجع الرد لمعرفة سبب الفشل |
مثال Python
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(
prompt: str,
negative_prompt: str = "",
width: int = 1280,
height: int = 720,
seed: int = -1,
) -> str:
payload = {
"prompt": prompt,
"negative_prompt": negative_prompt,
"width": width,
"height": height,
"seed": seed,
}
resp = requests.post(
f"{BASE_URL}/v3/async/hunyuan-video-fast",
headers=HEADERS,
json=payload,
)
resp.raise_for_status()
return resp.json()["task_id"]
def poll_result(task_id: str, interval: int = 5, timeout: int = 300) -> dict:
deadline = time.time() + timeout
while time.time() < deadline:
resp = requests.get(
f"{BASE_URL}/v3/async/task-result",
headers=HEADERS,
params={"task_id": task_id},
)
resp.raise_for_status()
data = resp.json()
status = data.get("task_status", "")
if status == "TASK_STATUS_SUCCEED":
return data
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Task failed: {data}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")
if __name__ == "__main__":
task_id = submit_video(
prompt="A red fox running through a snowy forest at dawn, slow motion, cinematic wide shot",
negative_prompt="blurry, low quality, distorted, watermark",
width=1280,
height=720,
)
print(f"Task submitted: {task_id}")
result = poll_result(task_id)
for video in result.get("videos", []):
print(f"Video URL (expires in {video['video_url_ttl']}s): {video['video_url']}")
مثال cURL
# Step 1: Submit the generation request
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/hunyuan-video-fast \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A timelapse of a city skyline transitioning from dusk to night, cinematic",
"negative_prompt": "blurry, low quality, distorted",
"width": 1280,
"height": 720,
"seed": 42
}' | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# Step 2: Poll until complete
while true; do
RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
-H "Authorization: Bearer $NOVITA_API_KEY")
STATUS=$(echo "$RESULT" | jq -r '.task_status')
if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
echo "$RESULT" | jq -r '.videos[0].video_url'
break
elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
echo "Failed: $RESULT"
break
fi
echo "Status: $STATUS — waiting..."
sleep 5
done
المعلمات الأساسية
| المعلمة | النوع | مطلوبة | الوصف |
|---|---|---|---|
prompt |
string | نعم | وصف نصي لمشهد الفيديو والموضوع والحركة والأسلوب |
negative_prompt |
string | لا | عناصر يجب تجنّبها في المخرجات (مثل “blurry, low quality”) |
width |
integer | لا | عرض المخرجات بالبكسل — راجع وثائق API للقيم المدعومة |
height |
integer | لا | ارتفاع المخرجات بالبكسل — يُستخدم مع width لتحديد الدقة |
seed |
integer | لا | عيّن عددًا صحيحًا ثابتًا لإعادة إنتاج نفس المخرجات؛ -1 لقيمة عشوائية |
للقائمة الكاملة للمعلمات، بما في ذلك خيارات المدة، والقيود القصوى للدقة، وأي حقول خاصة بالنموذج، راجع مرجع API الخاص بـ Hunyuan Video Fast.
التسعير والحدود
تحقق من تسعير كل فيديو حاليًا في صفحة نماذج Novita AI. تسعير توليد الفيديو عادةً يكون لكل مقطع ويختلف حسب الدقة والمدة. راجع صفحة التسعير قبل بناء نموذج تكلفة لأحمال الإنتاج.
تأكد من الحدود التالية في الوثائق الرسمية قبل النشر:
- الحد الأقصى لطول حرف الوصف
- قيم الدقة المدعومة (مجموعات العرض × الارتفاع)
- الحد الأقصى لمدة الفيديو بالثواني
- حدود المعدل وسقف المهام المتزامنة لكل مفتاح API
عادةً ما تكون النسخة السريعة أقل تكلفة لكل مقطع من النموذج القياسي بسبب انخفاض وقت الحوسبة — تحقق من الفرق الحالي في صفحة تسعير Novita.
استكشاف الأخطاء وإصلاحها
401 Unauthorized — مفتاح API مفقود أو غير صالح أو منتهي الصلاحية. تأكد من تعيين NOVITA_API_KEY وأن المفتاح نشط في لوحة تحكم Novita AI.
422 Unprocessable Entity — معلمة مطلوبة مفقودة أو قيمة خارج النطاق. تأكد من أن prompt غير فارغ وأن قيم width / height ضمن المجموعة المدعومة في وثائق API.
تبقى المهمة في حالة TASK_STATUS_PROCESSING — التوليد لا يزال قيد التشغيل. تكتمل النسخة السريعة أسرع من القياسية، لكن الدقة الأعلى والمدة الأطول تستغرقان وقتًا أكبر. زِد مهلة الاستقصاء للمخرجات الكبيرة.
يعيد video_url خطأ 403 أو 404 — انتهت صلاحية الرابط (انقضت video_url_ttl). في الإنتاج، نزّل الفيديو أو انقله فورًا بعد TASK_STATUS_SUCCEED — لا تعتمد على الرابط المستضاف كتخزين دائم.
مشاكل جودة متكررة لأنواع معينة من الأوصاف — انتقل إلى أسلوب تحسين prompt: صِف الموضوع والحركة وزاوية الكاميرا والأسلوب بوضوح. أضف مدخلات negative_prompt للعيوب الشائعة. إذا كانت الجودة ما تزال غير كافية لحالة الاستخدام، فقيّم نقطة نهاية Hunyuan Video القياسية.
الأسئلة الشائعة
ما هي نقطة نهاية Novita AI الخاصة بـ Hunyuan Video Fast؟
POST https://api.novita.ai/v3/async/hunyuan-video-fast. تعمل واجهة API بشكل غير متزامن: أرسل طلبًا، واستلم task_id، ثم استقصِ GET https://api.novita.ai/v3/async/task-result?task_id=<id> حتى تصبح task_status بقيمة TASK_STATUS_SUCCEED.
كيف يختلف Hunyuan Video Fast عن Hunyuan Video القياسي؟
النسخة السريعة محسّنة لسرعة التوليد — فهي تقلل الوقت من إرسال المهمة إلى اكتمال الفيديو. المقابل هو أن دقة الحركة والالتزام الدقيق بالوصف أقل من النموذج القياسي. استخدم النسخة السريعة لتكرار الوصف، أو مهام الدفعات عالية الإنتاجية، أو المراحل التجريبية؛ واستخدم القياسية للمخرجات النهائية عالية الجودة.
هل يمكنني تعيين مدة فيديو محددة؟
راجع مرجع API لمعرفة معلمات المدة المدعومة. بعض واجهات فيديو Novita تتيح حقل duration صريحًا؛ بينما يستخدم البعض الآخر قيمة افتراضية. تحقق قبل افتراض طول المقطع الافتراضي.
كيف يمكنني إعادة إنتاج مخرج فيديو معين؟
عيّن seed إلى عدد صحيح ثابت. نفس مجموعة seed وprompt وwidth وheight يجب أن تنتج مخرجات متسقة عبر عمليات التشغيل.
هل يدعم Hunyuan Video Fast تحويل الصورة إلى فيديو؟
Hunyuan Video Fast على Novita AI هو نموذج نص-إلى-فيديو. لتوليد صورة-إلى-فيديو على Novita، تحقق من نماذج I2V المتاحة مثل Kling أو Vidu أو Wan في صفحة نماذج Novita.
كم تبلغ تكلفة Hunyuan Video Fast على Novita AI؟
تحقق من التسعير الحالي في novita.ai/models. تسعير الفيديو لكل مقطع يمكن أن يتغير؛ تحقق دائمًا من صفحة التسعير قبل بناء تقديرات تكلفة الإنتاج.
هل Hunyuan Video Fast مناسب لخطوط إنتاج الفيديو في بيئة الإنتاج؟
نعم، مع المعالجة المناسبة. صمّم خط الإنتاج حول إرسال المهام غير المتزامن، واحفظ task_id لتتبع الحالة، ونزّل الفيديو فور اكتماله (قبل انتهاء video_url_ttl)، وعالج TASK_STATUS_FAILED باستراتيجية إعادة محاولة أو خطة بديلة.
