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

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة تطبيقات توليد مقاطع الفيديو من وان للتقدم للحصول على الخدمة المناسبة. بعد دخول الصفحة، انقر على زر “Acquire” كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد تسجيل الدخول، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح prompt، وسلوك التوليد action، وصورة الإطار الأول المرجعية image_url، والنموذج model، للحصول على النتيجة المعالجة. أولاً، نحتاج إلى تمرير حقل action، وقيمته هي text2video، والتي تتضمن نوعين من السلوك: توليد الفيديو من النص (text2video)، وتوليد الفيديو من الصورة (image2video). ثم نحتاج أيضًا إلى إدخال النموذج model، والذي يتضمن حاليًا النماذج الرئيسية التالية: wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v، والمحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح واجهة برمجة التطبيقات، يمكن اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج توليد الفيديو، والذي يتضمن بشكل رئيسي wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v.
  • action: سلوك مهمة توليد الفيديو هذه، والتي تتضمن بشكل رئيسي ثلاثة سلوكيات، وهي: توليد الفيديو من النص (text2video)، توليد الفيديو من الصورة (image2video). عند كونها توليد فيديو من النص، حاليًا تدعم فقط النموذج wan2.6-t2v، وعند كونها توليد فيديو من الصورة، تدعم حاليًا النماذج wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash.
  • image_url: عند اختيار سلوك توليد الفيديو من الصورة image2video، يجب تحميل رابط صورة الإطار الأول المرجعية، حاليًا تدعم فقط النماذج wan2.6-i2v، wan2.6-i2v-flash.
  • reference_video_urls: اختيارية عند توليد الفيديو من الصورة، تحدد روابط الفيديو المرجعية للتوليد، حاليًا تدعم فقط النموذج wan2.6-r2v.
  • size: تحدد دقة الفيديو الناتج، بالتنسيق عرض*ارتفاع. تعتمد القيمة الافتراضية والقيم القابلة للاستخدام على معلمة النموذج، يمكن الرجوع إلى وثائق الموقع الرسمي لمزيد من التفاصيل.
  • duration: مدة توليد الفيديو، تدعم بشكل رئيسي 5، 10، 15.
  • shot_type: اختيارية، تحدد نوع اللقطة في الفيديو الناتج، أي ما إذا كان الفيديو يتكون من لقطة مستمرة واحدة أو عدة لقطات متغيرة. شروط السريان: سارية فقط عندما يكون “prompt_extend”: true. أولوية المعلمات: shot_type > prompt. على سبيل المثال، إذا تم تعيين shot_type إلى “single”، حتى لو كانت prompt تحتوي على “توليد فيديو متعدد اللقطات”، سيظل النموذج ينتج فيديو بلقطة واحدة، يمكن الرجوع إلى وثائق الموقع الرسمي لمزيد من التفاصيل.
  • negative_prompt: اختيارية، كلمات التلميح العكسية، تستخدم لوصف المحتوى الذي لا ترغب في رؤيته في مشهد الفيديو، يمكن أن تحد من مشهد الفيديو. تدعم اللغتين العربية والإنجليزية، ويجب ألا يتجاوز الطول 500 حرف، وسيتم قطع الجزء الزائد تلقائيًا. قيم مثال: دقة منخفضة، أخطاء، أسوأ جودة، جودة منخفضة، عيوب، أصابع زائدة، نسب غير صحيحة، إلخ.
  • resolution: تحدد مستوى دقة الفيديو الناتج، تستخدم لضبط وضوح الفيديو (إجمالي البكسلات). يقوم النموذج بتعديل الحجم تلقائيًا إلى إجمالي بكسلات قريب بناءً على مستوى الدقة المختار، وسيتم الحفاظ على نسبة العرض إلى الارتفاع للفيديو قدر الإمكان مع نسبة العرض إلى الارتفاع للصورة المدخلة img_url، لمزيد من التفاصيل، يرجى الرجوع إلى وثائق الموقع الرسمي.
  • audio_url: رابط ملف الصوت، سيستخدم النموذج هذا الصوت لتوليد الفيديو. طريقة الاستخدام مرجعية وثائق الموقع الرسمي.
  • audio: هل يتم توليد فيديو صوتي. أولوية المعلمات: audio > audio_url. عندما يكون audio=false، حتى لو تم تمرير audio_url، ستظل النتيجة فيديو بدون صوت، وسيتم احتساب التكلفة كفيديو بدون صوت، القيمة الافتراضية هي true.
  • prompt_extend: هل يتم تفعيل إعادة كتابة التلميح الذكي. عند التفعيل، يستخدم النموذج الكبير لإعادة كتابة التلميح المدخل بشكل ذكي. بالنسبة للتلميحات القصيرة، يكون تحسين النتائج ملحوظًا، ولكن سيزيد من وقت المعالجة، القيمة الافتراضية هي true.
  • prompt: كلمة التلميح.
  • callback_url: URL الذي يحتاج إلى استدعاء النتائج.
بعد الاختيار، يمكنك أن ترى أن الجانب الأيمن قد تم توليد الكود المقابل أيضًا، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء الاختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
  • video_url: رابط الفيديو الناتج لمهمة توليد الفيديو في ذلك الوقت.
  • state: حالة مهمة توليد الفيديو في ذلك الوقت.
يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على الفيديو الناتج من خلال رابط الفيديو video_url في النتيجة. بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل، يمكنك نسخه مباشرة، على سبيل المثال، كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/wan/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "wan2.6-t2v",
  "prompt": "Astronauts shuttle from space to volcano",
  "duration": 5
}'

​
وظيفة توليد الفيديو من الصورة

如果想对参考图或者参考视频来生成视频的话，可以将参数 action 设置为 image2video ，并且输入需要参考图链接或者参考视频链接，接下来我们要必须填下一步需要扩展的提示词来自定义生成视频，就可以指定如下内容：
  • model：生成视频的模型，主要有 wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v 模型。
  • image_url：当选择图生视频行为 image2video 就必须需要上传的首帧参考图片链接，目前只支持模型 wan2.6-i2v、wan2.6-i2v-flash。
  • reference_video_urls：图生视频时可选，指定参考的视频链接进行生成，目前只支持模型 wan2.6-r2v。
  • prompt：提示词。
填写样例如下：

填写完毕之后自动生成了代码如下：

对应的 Python 代码： 
import requests

url = "https://api.acedata.cloud/wan/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "image2video",
    "model": "wan2.6-i2v",
    "prompt": "Astronauts shuttle from space to volcano",
    "duration": 5,
    "image_url": "https://cdn.acedata.cloud/r9vsv9.png",
    "callback_url": "https://www.baidu.com/"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
点击运行，可以发现会得到一个结果，如下： 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
可以看出，结果内容与上文的是一致的，这也就实现视频的扩展视频功能。

​
异步回调

由于 Wan Videos Generation API生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。 整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成视频的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。 下面我们通过示例来了解下具体怎样操作。 首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示： 将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3。 接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下： 
{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}
稍等片刻，我们可以在 https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 上观察到生成视频的结果，如图所示： 内容如下： 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}
可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

​
错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 400 token_mismatched：请求错误，可能是由于缺少或无效的参数。
  • 400 api_not_implemented：请求错误，可能是由于缺少或无效的参数。
  • 401 invalid_token：未授权，授权令牌无效或缺失。
  • 429 too_many_requests：请求过多，超出了速率限制。
  • 500 api_error：内部服务器错误，服务器出现问题。

​
错误响应示例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
结论

通过本文档，您已经了解了如何使用 Wan Videos Generation API 可通过输入提示词以及首帧参考图片来生成视频。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。