---
read_when:
    - تولید ویدئو از طریق عامل
    - پیکربندی ارائه‌دهندگان و مدل‌های تولید ویدئو
    - درک پارامترهای ابزار video_generate
sidebarTitle: Video generation
summary: تولید ویدئو از طریق `video_generate` با استفاده از ارجاعات متنی، تصویری یا ویدئویی در 16 بک‌اند ارائه‌دهنده
title: تولید ویدئو
x-i18n:
    generated_at: "2026-07-27T17:13:52Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 4afc9338fdfdc269b50b949b6d1a186e3a2064ed4ee40a41722efea40ae791aa
    source_path: tools/video-generation.md
    workflow: 16
---

عامل‌های OpenClaw از طریق `video_generate`، از اعلان‌های متنی، تصاویر مرجع یا
ویدئوهای موجود، ویدئو تولید می‌کنند. شانزده بک‌اند ارائه‌دهنده
پشتیبانی می‌شوند؛ عامل بر اساس پیکربندی و کلیدهای API
موجود، به‌طور خودکار گزینه مناسب را انتخاب می‌کند.

<Note>
`video_generate` تنها زمانی نمایش داده می‌شود که دست‌کم یک ارائه‌دهنده تولید ویدئو
در دسترس باشد. اگر در ابزارهای عامل موجود نیست، کلید API یک ارائه‌دهنده را تنظیم یا
`agents.defaults.mediaModels.video` را پیکربندی کنید.
</Note>

`video_generate` سه حالت زمان اجرا دارد که از ورودی‌های مرجع
در فراخوانی تعیین می‌شوند:

- `generate` - بدون رسانه مرجع (متن‌به‌ویدئو).
- `imageToVideo` - یک یا چند تصویر مرجع.
- `videoToVideo` - یک یا چند ویدئوی مرجع.

ارائه‌دهندگان می‌توانند از هر زیرمجموعه‌ای از این حالت‌ها پشتیبانی کنند. ابزار پیش از
ارسال، حالت فعال را اعتبارسنجی می‌کند و حالت‌های پشتیبانی‌شده را در `action=list`
گزارش می‌دهد.

## شروع سریع

<Steps>
  <Step title="پیکربندی احراز هویت">
    برای هر ارائه‌دهنده پشتیبانی‌شده، یک کلید API تنظیم کنید:

    ```bash
    export GEMINI_API_KEY="your-key"
    ```

  </Step>
  <Step title="انتخاب مدل پیش‌فرض (اختیاری)">
    ```bash
    openclaw config set agents.defaults.mediaModels.video.primary "google/veo-3.1-fast-generate-preview"
    ```
  </Step>
  <Step title="درخواست از عامل">
    > یک ویدئوی سینمایی ۵ثانیه‌ای از یک خرچنگ دریایی صمیمی که هنگام غروب موج‌سواری می‌کند، تولید کن.

    عامل به‌طور خودکار `video_generate` را فراخوانی می‌کند. نیازی به
    افزودن ابزار به فهرست مجاز نیست.

  </Step>
</Steps>

## سازوکار تولید ناهمگام

تولید ویدئو ناهمگام است:

1. OpenClaw درخواست را برای ارائه‌دهنده ارسال می‌کند و بلافاصله یک شناسه وظیفه برمی‌گرداند.
2. ارائه‌دهنده کار را در پس‌زمینه پردازش می‌کند (معمولاً بسته به ارائه‌دهنده و وضوح، از 30 ثانیه تا چند دقیقه؛ ارائه‌دهندگان کند مبتنی بر صف می‌توانند تا مهلت زمانی پیکربندی‌شده اجرا شوند).
3. وقتی ویدئو آماده شود، OpenClaw همان نشست را با یک رویداد تکمیل داخلی بیدار می‌کند.
4. عامل آن را از طریق حالت عادی پاسخ قابل‌مشاهده نشست گزارش می‌کند:
   پاسخ نهایی خودکار، یا `message(action="send")` هنگامی که نشست به
   ابزار پیام نیاز دارد. اگر نشست درخواست‌کننده غیرفعال باشد، یا بیدارسازی آن ناموفق شود و
   رسانه تولیدشده همچنان در پاسخ تکمیل وجود نداشته باشد، OpenClaw یک
   جایگزین مستقیم و هم‌توان با رسانه ارسال می‌کند.

هنگامی که کاری در حال اجراست، فراخوانی‌های تکراری `video_generate` در همان
نشست، به‌جای شروع تولیدی دیگر، وضعیت فعلی وظیفه را برمی‌گردانند.
برای بررسی بدون راه‌اندازی تولید جدید از `action: "status"`، یا از
`openclaw tasks list` / `openclaw tasks show <lookup>` در CLI استفاده کنید
([وظایف پس‌زمینه](/fa/automation/tasks) را ببینید).

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

وقتی ارائه‌دهنده بایت برگرداند، فایل‌های ویدئویی تولیدشده در فضای ذخیره‌سازی رسانه
تحت مدیریت OpenClaw ذخیره می‌شوند. سقف پیش‌فرض 16MB است (محدودیت مشترک رسانه
ویدئویی)؛ `agents.defaults.mediaMaxMb` آن را برای رندرهای بزرگ‌تر افزایش می‌دهد. هنگامی که
ارائه‌دهنده یک نشانی اینترنتی خروجی میزبانی‌شده نیز برمی‌گرداند، اگر ماندگارسازی محلی
فایل بیش‌ازحد بزرگ را رد کند، OpenClaw به‌جای ناموفق کردن وظیفه، آن نشانی اینترنتی
را تحویل می‌دهد.

### چرخه عمر وظیفه

| وضعیت       | معنا                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `queued`    | وظیفه ایجاد شده و منتظر پذیرش آن از سوی ارائه‌دهنده است.                                                   |
| `running`   | ارائه‌دهنده در حال پردازش است (معمولاً بسته به ارائه‌دهنده و وضوح، از 30 ثانیه تا چند دقیقه). |
| `succeeded` | ویدئو آماده است؛ عامل بیدار می‌شود و آن را در گفت‌وگو ارسال می‌کند.                                         |
| `failed`    | خطای ارائه‌دهنده یا پایان مهلت زمانی؛ عامل با جزئیات خطا بیدار می‌شود.                                         |

وضعیت را از CLI بررسی کنید:

```bash
openclaw tasks list
openclaw tasks show <lookup>
openclaw tasks cancel <lookup>
```

## ارائه‌دهندگان پشتیبانی‌شده

| ارائه‌دهنده              | مدل پیش‌فرض                   | متن | مرجع تصویر                                            | مرجع ویدئو                                       | احراز هویت                                     |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba               | `wan2.6-t2v`                    |  ✓   | بله (نشانی اینترنتی راه‌دور)                                     | بله (نشانی اینترنتی راه‌دور)                                | `MODELSTUDIO_API_KEY`                    |
| BytePlus (همراه)    | `seedance-1-0-pro-250528`       |  ✓   | تا 2 تصویر (فریم اول + آخر)                  | -                                               | `BYTEPLUS_API_KEY`                       |
| Plugin نسخه 1.5 ‏BytePlus   | `seedance-1-5-pro-251215`       |  ✓   | تا 2 تصویر (فریم اول + آخر از طریق نقش)         | -                                               | `BYTEPLUS_API_KEY`                       |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128`  |  ✓   | تا 9 تصویر مرجع                             | تا 3 ویدئو                                  | `BYTEPLUS_API_KEY`                       |
| ComfyUI               | `workflow`                      |  ✓   | 1 تصویر                                              | -                                               | `COMFY_API_KEY` یا `COMFY_CLOUD_API_KEY` |
| DeepInfra             | `Pixverse/Pixverse-T2V`         |  ✓   | -                                                    | -                                               | `DEEPINFRA_API_KEY`                      |
| fal                   | `fal-ai/minimax/video-01-live`  |  ✓   | 1 تصویر؛ با تبدیل مرجع‌به‌ویدئوی Seedance تا 9 تصویر    | با تبدیل مرجع‌به‌ویدئوی Seedance تا 3 ویدئو | `FAL_KEY`                                |
| Google                | `veo-3.1-fast-generate-preview` |  ✓   | 1 تصویر                                              | 1 ویدئو                                         | `GEMINI_API_KEY`                         |
| MiniMax               | `MiniMax-Hailuo-2.3`            |  ✓   | 1 تصویر                                              | -                                               | `MINIMAX_API_KEY` یا OAuth ‏MiniMax       |
| OpenAI                | `sora-2`                        |  ✓   | 1 تصویر                                              | 1 ویدئو                                         | `OPENAI_API_KEY`                         |
| OpenRouter            | `google/veo-3.1-fast`           |  ✓   | تا 4 تصویر (فریم اول/آخر یا مراجع)      | -                                               | `OPENROUTER_API_KEY`                     |
| Qwen                  | `wan2.6-t2v`                    |  ✓   | بله (نشانی اینترنتی راه‌دور)                                     | بله (نشانی اینترنتی راه‌دور)                                | `QWEN_API_KEY`                           |
| Runway                | `gen4.5`                        |  ✓   | 1 تصویر                                              | 1 ویدئو                                         | `RUNWAYML_API_SECRET`                    |
| Together              | `Wan-AI/Wan2.2-T2V-A14B`        |  ✓   | فقط `Wan-AI/Wan2.2-I2V-A14B`                        | -                                               | `TOGETHER_API_KEY`                       |
| Vydra                 | `veo3`                          |  ✓   | 1 تصویر (`kling`)                                    | -                                               | `VYDRA_API_KEY`                          |
| xAI                   | `grok-imagine-video`            |  ✓   | کلاسیک: 1 فریم اول یا 7 مرجع؛ 1.5: ‏1 فریم | کلاسیک: 1 ویدئو                                | `XAI_API_KEY`                            |

برخی ارائه‌دهندگان متغیرهای محیطی کلید API اضافی یا جایگزین را می‌پذیرند. برای
جزئیات، [صفحه‌های ارائه‌دهندگان](#related) را ببینید.

برای بررسی ارائه‌دهندگان، مدل‌ها و حالت‌های زمان اجرای موجود در زمان اجرا،
`video_generate action=list` را اجرا کنید.

### ماتریس قابلیت‌ها

قرارداد صریح حالت که توسط `video_generate`، آزمون‌های قرارداد و
پویش زنده مشترک استفاده می‌شود:

| ارائه‌دهنده   | `generate` | `imageToVideo` | `videoToVideo` | مسیرهای زنده مشترک امروز                                                                                                                 |
| ---------- | :--------: | :------------: | :------------: | --------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba    |     ✓      |       ✓        |       ✓        | `generate`، `imageToVideo`؛ `videoToVideo` رد می‌شود، زیرا این ارائه‌دهنده به نشانی‌های اینترنتی راه‌دور ویدئوی `http(s)` نیاز دارد                              |
| BytePlus   |     ✓      |       ✓        |       -        | `generate`، `imageToVideo`                                                                                                              |
| ComfyUI    |     ✓      |       ✓        |       -        | در پویش مشترک نیست؛ پوشش ویژه گردش کار در آزمون‌های Comfy قرار دارد                                                              |
| DeepInfra  |     ✓      |       -        |       -        | `generate`؛ طرح‌واره‌های بومی ویدئوی DeepInfra در قرارداد Plugin از نوع متن‌به‌ویدئو هستند                                                     |
| fal        |     ✓      |       ✓        |       ✓        | `generate`، `imageToVideo`؛ `videoToVideo` فقط هنگام استفاده از تبدیل مرجع‌به‌ویدئوی Seedance                                                  |
| Google     |     ✓      |       ✓        |       ✓        | `generate`، `imageToVideo`؛ `videoToVideo` مشترک رد می‌شود، زیرا پویش فعلی Gemini/Veo مبتنی بر بافر آن ورودی را نمی‌پذیرد |
| MiniMax    |     ✓      |       ✓        |       -        | `generate`، `imageToVideo`                                                                                                              |
| OpenAI     |     ✓      |       ✓        |       ✓        | `generate`، `imageToVideo`؛ `videoToVideo` مشترک رد می‌شود، زیرا این مسیر سازمان/ورودی در حال حاضر به دسترسی ویرایش ویدئو در سمت ارائه‌دهنده نیاز دارد   |
| OpenRouter |     ✓      |       ✓        |       -        | `generate`، `imageToVideo`                                                                                                              |
| Qwen       |     ✓      |       ✓        |       ✓        | `generate`، `imageToVideo`؛ `videoToVideo` رد می‌شود، زیرا این ارائه‌دهنده به نشانی‌های اینترنتی راه‌دور ویدئوی `http(s)` نیاز دارد                              |
| Runway     |     ✓      |       ✓        |       ✓        | `generate`، `imageToVideo`؛ `videoToVideo` فقط هنگامی اجرا می‌شود که مدل انتخاب‌شده `runway/gen4_aleph` باشد                                     |
| Together   |     ✓      |       ✓        |       -        | `generate`، `imageToVideo`                                                                                                              |
| Vydra      |     ✓      |       ✓        |       -        | `generate`؛ `imageToVideo` مشترک رد می‌شود، زیرا `veo3` همراه فقط متنی است و `kling` همراه به نشانی اینترنتی تصویر راه‌دور نیاز دارد           |
| xAI        |     ✓      |       ✓        |       ✓        | نسخه کلاسیک از همه حالت‌ها پشتیبانی می‌کند؛ Video 1.5 فقط تصویر‌به‌ویدئو است؛ ورودی MP4 راه‌دور، `videoToVideo` را از پویش مشترک خارج نگه می‌دارد             |

## پارامترهای ابزار

### الزامی

<ParamField path="prompt" type="string" required>
  توضیح متنی ویدیویی که باید تولید شود. برای `action: "generate"` الزامی است.
</ParamField>

### ورودی‌های محتوا

<ParamField path="image" type="string">یک تصویر مرجع (مسیر یا URL).</ParamField>
<ParamField path="images" type="string[]">چند تصویر مرجع (حداکثر 9).</ParamField>
<ParamField path="imageRoles" type="string[]">
راهنمای اختیاری نقش برای هر موقعیت، به‌موازات فهرست ترکیبی تصاویر.
مقادیر متعارف: `first_frame`، `last_frame`، `reference_image`.
</ParamField>
<ParamField path="video" type="string">یک ویدیوی مرجع (مسیر یا URL).</ParamField>
<ParamField path="videos" type="string[]">چند ویدیوی مرجع (حداکثر 4).</ParamField>
<ParamField path="videoRoles" type="string[]">
راهنمای اختیاری نقش برای هر موقعیت، به‌موازات فهرست ترکیبی ویدیوها.
مقدار متعارف: `reference_video`.
</ParamField>
<ParamField path="audioRef" type="string">
یک صوت مرجع (مسیر یا URL). هنگامی‌که ارائه‌دهنده از ورودی‌های صوتی پشتیبانی کند،
برای موسیقی پس‌زمینه یا مرجع صدا استفاده می‌شود.
</ParamField>
<ParamField path="audioRefs" type="string[]">چند صوت مرجع (حداکثر 3).</ParamField>
<ParamField path="audioRoles" type="string[]">
راهنمای اختیاری نقش برای هر موقعیت، به‌موازات فهرست ترکیبی صوت‌ها.
مقدار متعارف: `reference_audio`.
</ParamField>

<Note>
راهنماهای نقش بدون تغییر به ارائه‌دهنده ارسال می‌شوند. مقادیر متعارف از
اجتماع `VideoGenerationAssetRole` می‌آیند، اما ارائه‌دهندگان ممکن است رشته‌های نقش
دیگری را نیز بپذیرند. آرایه‌های `*Roles` نباید تعداد ورودی بیشتری از
فهرست مرجع متناظر داشته باشند؛ خطاهای یک‌واحدی با خطایی واضح ناموفق می‌شوند.
برای تعیین‌نشده باقی‌گذاشتن یک جایگاه، از رشته خالی استفاده کنید. برای xAI، جهت
استفاده از حالت تولید `reference_images` آن، نقش همه تصاویر را روی
`reference_image` تنظیم کنید؛ برای تبدیل تک‌تصویر به ویدیو، نقش را حذف کنید
یا از `first_frame` استفاده کنید.
</Note>

### کنترل‌های سبک

<ParamField path="aspectRatio" type="string">
  راهنمای نسبت ابعاد مانند `1:1`، `16:9`، `9:16`، `adaptive` یا مقداری ویژه ارائه‌دهنده. OpenClaw مقادیر پشتیبانی‌نشده را متناسب با ارائه‌دهنده نرمال‌سازی یا نادیده می‌گیرد.
</ParamField>
<ParamField path="resolution" type="string">راهنمای وضوح مانند `360P`، `480P`، `540P`، `720P`، `768P`، `1080P`، `4K` یا مقداری ویژه ارائه‌دهنده. OpenClaw مقادیر پشتیبانی‌نشده را متناسب با ارائه‌دهنده نرمال‌سازی یا نادیده می‌گیرد.</ParamField>
<ParamField path="durationSeconds" type="number">
  مدت‌زمان هدف برحسب ثانیه (گردشده به نزدیک‌ترین مقدار پشتیبانی‌شده توسط ارائه‌دهنده).
</ParamField>
<ParamField path="size" type="string">راهنمای اندازه، هنگامی‌که ارائه‌دهنده از آن پشتیبانی می‌کند.</ParamField>
<ParamField path="audio" type="boolean">
  فعال‌سازی صوت تولیدشده در خروجی، در صورت پشتیبانی. متمایز از `audioRef*` (ورودی‌ها).
</ParamField>
<ParamField path="watermark" type="boolean">فعال یا غیرفعال‌کردن واترمارک ارائه‌دهنده، در صورت پشتیبانی.</ParamField>

`adaptive` یک مقدار نگهبان ویژه ارائه‌دهنده است: همان‌طور که هست به
ارائه‌دهندگانی ارسال می‌شود که `adaptive` را در قابلیت‌های خود اعلام
می‌کنند (برای نمونه، BytePlus Seedance از آن برای تشخیص خودکار نسبت از ابعاد
تصویر ورودی استفاده می‌کند). ارائه‌دهندگانی که آن را اعلام نمی‌کنند، مقدار را
از طریق `details.ignoredOverrides` در نتیجه ابزار نمایش می‌دهند تا حذف آن قابل مشاهده باشد.

### پیشرفته

<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
  `"status"` وظیفه جاری نشست را برمی‌گرداند؛ `"list"` ارائه‌دهندگان را بررسی می‌کند.
</ParamField>
<ParamField path="model" type="string">بازنویسی ارائه‌دهنده/مدل (برای نمونه، `runway/gen4.5`).</ParamField>
<ParamField path="filename" type="string">راهنمای نام فایل خروجی.</ParamField>
<ParamField path="timeoutMs" type="number">مهلت زمانی اختیاری عملیات ارائه‌دهنده برحسب میلی‌ثانیه. در صورت حذف، OpenClaw در صورت پیکربندی از `agents.defaults.mediaModels.video.timeoutMs` استفاده می‌کند؛ در غیر این صورت، اگر پیش‌فرضی وجود داشته باشد، از پیش‌فرض ارائه‌دهنده تعیین‌شده توسط نویسنده Plugin استفاده می‌شود.</ParamField>
<ParamField path="providerOptions" type="object">
  گزینه‌های ویژه ارائه‌دهنده به‌شکل یک شیء JSON (برای نمونه، `{"seed": 42, "draft": true}`).
  ارائه‌دهندگانی که شِمای نوع‌دار اعلام می‌کنند، کلیدها و نوع‌ها را اعتبارسنجی
  می‌کنند؛ کلیدهای ناشناخته یا عدم تطابق نوع‌ها باعث می‌شود نامزد در هنگام
  بازگشت جایگزین نادیده گرفته شود. ارائه‌دهندگان فاقد شِمای اعلام‌شده، گزینه‌ها
  را بدون تغییر دریافت می‌کنند. برای مشاهده موارد پذیرفته‌شده توسط هر
  ارائه‌دهنده، `video_generate action=list` را اجرا کنید.
</ParamField>

<Note>
همه ارائه‌دهندگان از همه پارامترها پشتیبانی نمی‌کنند. OpenClaw مدت‌زمان را به
نزدیک‌ترین مقدار پشتیبانی‌شده توسط ارائه‌دهنده نرمال‌سازی می‌کند و هنگامی‌که
یک ارائه‌دهنده جایگزین سطح کنترل متفاوتی ارائه دهد، راهنماهای هندسی ترجمه‌شده
مانند تبدیل اندازه به نسبت ابعاد را نگاشت مجدد می‌کند. بازنویسی‌هایی که واقعاً
پشتیبانی نمی‌شوند، بر مبنای بهترین تلاش نادیده گرفته می‌شوند و در نتیجه ابزار
به‌صورت هشدار گزارش می‌شوند. محدودیت‌های قطعی قابلیت (مانند تعداد بیش‌ازحد
ورودی‌های مرجع) پیش از ارسال باعث شکست می‌شوند. نتایج ابزار تنظیمات اعمال‌شده
را گزارش می‌کنند؛ `details.normalization` هرگونه ترجمه از مقدار درخواستی به
مقدار اعمال‌شده را ثبت می‌کند.
</Note>

ورودی‌های مرجع حالت زمان اجرا را انتخاب می‌کنند:

- بدون رسانه مرجع -> `generate`
- هرگونه مرجع تصویری -> `imageToVideo`
- هرگونه مرجع ویدیویی -> `videoToVideo`
- ورودی‌های صوتی مرجع حالت حل‌شده را **تغییر نمی‌دهند**؛ آن‌ها روی
  حالتی اعمال می‌شوند که مراجع تصویر/ویدیو انتخاب کرده‌اند و فقط با
  ارائه‌دهندگانی کار می‌کنند که `maxInputAudios` را اعلام می‌کنند.

ترکیب مراجع تصویر و ویدیو یک سطح قابلیت مشترک و پایدار نیست.
در هر درخواست، یک نوع مرجع را ترجیح دهید.

#### بازگشت جایگزین و گزینه‌های نوع‌دار

برخی بررسی‌های قابلیت در لایه بازگشت جایگزین انجام می‌شوند، نه در مرز ابزار؛
بنابراین درخواستی که از محدودیت‌های ارائه‌دهنده اصلی فراتر می‌رود، همچنان
می‌تواند روی یک ارائه‌دهنده جایگزین توانمند اجرا شود:

- نامزد فعال که `maxInputAudios` (یا `0`) را اعلام نکرده باشد، هنگامی‌که
  درخواست شامل مراجع صوتی است نادیده گرفته می‌شود؛ نامزد بعدی امتحان می‌شود.
  همین محدودیت برای شمار مراجع تصویر و ویدیو در برابر
  `maxInputImages`/`maxInputVideos` نیز اعمال می‌شود.
- اگر `maxDurationSeconds` نامزد فعال از `durationSeconds` درخواستی کمتر باشد
  و فهرست `supportedDurationSeconds` اعلام نشده باشد، نامزد نادیده گرفته می‌شود.
- اگر درخواست شامل `providerOptions` باشد و نامزد فعال صراحتاً
  شِمای نوع‌دار `providerOptions` را اعلام کند، در صورتی نادیده گرفته می‌شود
  که کلیدهای ارائه‌شده در شِما نباشند یا نوع مقادیر مطابقت نداشته باشد.
  ارائه‌دهندگان فاقد شِمای اعلام‌شده، گزینه‌ها را بدون تغییر دریافت می‌کنند
  (عبور مستقیم سازگار با نسخه‌های پیشین). یک ارائه‌دهنده می‌تواند با اعلام
  یک شِمای خالی (`capabilities.providerOptions: {}`) همه گزینه‌های ارائه‌دهنده را
  غیرفعال کند که باعث همان نادیده‌گرفتن ناشی از عدم تطابق نوع می‌شود.

نخستین دلیل نادیده‌گرفتن در یک درخواست در سطح `warn` ثبت می‌شود تا
اپراتورها ببینند چه زمانی ارائه‌دهنده اصلی آن‌ها کنار گذاشته شده است؛ دلایل
بعدی در سطح `debug` ثبت می‌شوند تا زنجیره‌های طولانی بازگشت جایگزین
کم‌صدا بمانند. اگر همه نامزدها نادیده گرفته شوند، خطای تجمیعی دلیل
نادیده‌گرفتن هرکدام را دربر می‌گیرد.

## کنش‌ها

| کنش     | کاری که انجام می‌دهد                                                                                             |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `generate` | پیش‌فرض. از درخواست متنی داده‌شده و ورودی‌های مرجع اختیاری، ویدیو ایجاد می‌کند.                             |
| `status`   | بدون آغاز تولیدی دیگر، وضعیت وظیفه ویدیویی در حال اجرا را برای نشست جاری بررسی می‌کند. |
| `list`     | ارائه‌دهندگان، مدل‌ها و قابلیت‌های موجود آن‌ها را نمایش می‌دهد.                                                |

## انتخاب مدل

OpenClaw مدل را به‌ترتیب زیر تعیین می‌کند:

1. **پارامتر ابزار `model`** - اگر عامل در فراخوانی یکی را مشخص کند.
2. **`videoGenerationModel.primary`** از پیکربندی.
3. **`videoGenerationModel.fallbacks`** به‌ترتیب.
4. **تشخیص خودکار** - ارائه‌دهندگانی که احراز هویت معتبر دارند؛ ابتدا
   ارائه‌دهنده پیش‌فرض جاری و سپس ارائه‌دهندگان باقی‌مانده به‌ترتیب الفبایی.

اگر یک ارائه‌دهنده ناموفق باشد، نامزد بعدی به‌طور خودکار امتحان می‌شود. اگر
همه نامزدها ناموفق باشند، خطا جزئیات هر تلاش را دربر می‌گیرد.

بازگشت خودکار میان ارائه‌دهندگان احراز هویت‌شده همیشه فعال است. مقدار
`model` در هر فراخوانی همچنان مرجع نهایی است.

```json5
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
        fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],
        timeoutMs: 180000, // بازنویسی اختیاری مهلت زمانی درخواست ارائه‌دهنده برای هر ابزار
      },
    },
  },
}
```

## نکات ارائه‌دهندگان

<AccordionGroup>
  <Accordion title="Alibaba">
    از نقطه پایانی ناهمگام DashScope / Model Studio استفاده می‌کند. تصاویر و
    ویدیوهای مرجع باید URLهای راه‌دور `http(s)` باشند.
  </Accordion>
  <Accordion title="BytePlus (همراه)">
    شناسه ارائه‌دهنده: `byteplus`.

    مدل‌ها: `seedance-1-0-pro-250528` (پیش‌فرض)،
    `seedance-1-5-pro-251215`.

    از API یکپارچه `content[]` استفاده می‌کند. حداکثر از 2 تصویر ورودی
    (`first_frame` + `last_frame`) پشتیبانی می‌کند. تصاویر را بر اساس
    موقعیت ارسال کنید یا `role` هر تصویر را صراحتاً تنظیم کنید.

    کلیدهای پشتیبانی‌شده `providerOptions`: `seed` (عدد)، `draft` (بولی -
    480p را اجباری می‌کند)، `camera_fixed` (بولی).

  </Accordion>
  <Accordion title="Plugin مربوط به BytePlus Seedance 1.5">
    به Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
    نیاز دارد (خارجی و همراه نیست). شناسه ارائه‌دهنده: `byteplus-seedance15`. مدل:
    `seedance-1-5-pro-251215`.

    از API یکپارچه `content[]` استفاده می‌کند. حداکثر از 2 تصویر ورودی
    (`first_frame` + `last_frame`) پشتیبانی می‌کند. همه ورودی‌ها باید
    URLهای راه‌دور `https://` باشند. `role: "first_frame"` / `"last_frame"`
    را روی هر تصویر تنظیم کنید یا تصاویر را بر اساس موقعیت ارسال کنید.

    `aspectRatio: "adaptive"` نسبت را از تصویر ورودی به‌طور خودکار تشخیص می‌دهد.
    `audio: true` به `generate_audio` نگاشت می‌شود. `providerOptions.seed`
    (عدد) ارسال می‌شود.

  </Accordion>
  <Accordion title="BytePlus Seedance 2.0">
    به Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark)
    نیاز دارد (خارجی و همراه نیست). شناسه ارائه‌دهنده: `byteplus-seedance2`. مدل‌ها:
    `dreamina-seedance-2-0-260128`،
    `dreamina-seedance-2-0-fast-260128`.

    از API یکپارچه `content[]` استفاده می‌کند. حداکثر از 9 تصویر مرجع،
    3 ویدیوی مرجع و 3 صوت مرجع پشتیبانی می‌کند. همه ورودی‌ها باید URLهای
    راه‌دور `https://` باشند. `role` را روی هر دارایی تنظیم کنید -
    مقادیر پشتیبانی‌شده:
    `"first_frame"`، `"last_frame"`، `"reference_image"`،
    `"reference_video"`، `"reference_audio"`.

    `aspectRatio: "adaptive"` نسبت را از تصویر ورودی به‌طور خودکار تشخیص می‌دهد.
    `audio: true` به `generate_audio` نگاشت می‌شود. `providerOptions.seed`
    (عدد) ارسال می‌شود.

  </Accordion>
  <Accordion title="ComfyUI">
    اجرای محلی یا ابری مبتنی بر گردش‌کار. از تبدیل متن به ویدیو و
    تصویر به ویدیو از طریق گراف پیکربندی‌شده پشتیبانی می‌کند.
  </Accordion>
  <Accordion title="fal">
    برای کارهای طولانی‌مدت از جریانی مبتنی بر صف استفاده می‌کند. OpenClaw به‌طور پیش‌فرض تا 20
    دقیقه منتظر می‌ماند و سپس کار در حال اجرای صف fal را پایان‌یافته بر اثر
    اتمام مهلت تلقی می‌کند. بیشتر مدل‌های ویدیویی fal
    یک ارجاع تصویر را می‌پذیرند. مدل‌های تبدیل ارجاع به ویدیوی Seedance 2.0
    حداکثر 9 تصویر، 3 ویدیو و 3 ارجاع صوتی را می‌پذیرند، با
    حداکثر 12 فایل ارجاع در مجموع.
  </Accordion>
  <Accordion title="Google (Gemini / Veo)">
    از یک ارجاع تصویر یا یک ارجاع ویدیو پشتیبانی می‌کند. درخواست‌های صوت تولیدشده
    در مسیر API مربوط به Gemini با یک هشدار نادیده گرفته می‌شوند، زیرا آن API
    پارامتر `generateAudio` را برای تولید ویدیوی کنونی Veo رد می‌کند.
  </Accordion>
  <Accordion title="MiniMax">
    فقط یک ارجاع تصویر. MiniMax وضوح‌های `768P` و `1080P`
    را می‌پذیرد؛ درخواست‌هایی مانند `720P` پیش از ارسال به نزدیک‌ترین
    مقدار پشتیبانی‌شده نرمال‌سازی می‌شوند.
  </Accordion>
  <Accordion title="OpenAI">
    فقط بازنویسی `size` ارسال می‌شود. سایر بازنویسی‌های سبک
    (`aspectRatio`، `resolution`، `audio`، `watermark`) با
    یک هشدار نادیده گرفته می‌شوند.
  </Accordion>
  <Accordion title="OpenRouter">
    از API ناهمگام `/videos` متعلق به OpenRouter استفاده می‌کند. OpenClaw
    کار را ارسال می‌کند، `polling_url` را پایش می‌کند و یکی از `unsigned_urls` یا
    نقطه پایانی مستندشدهٔ محتوای کار را بارگیری می‌کند. مقدار پیش‌فرض همراهِ `google/veo-3.1-fast`
    مدت‌زمان‌های 4/6/8 ثانیه، وضوح‌های `720P`/`1080P` و
    نسبت‌های تصویر `16:9`/`9:16` را اعلام می‌کند.
  </Accordion>
  <Accordion title="Qwen">
    همان بک‌اند DashScope متعلق به Alibaba. ورودی‌های ارجاع باید URLهای راه‌دور
    `http(s)` باشند؛ فایل‌های محلی از ابتدا رد می‌شوند.
  </Accordion>
  <Accordion title="Runway">
    از فایل‌های محلی از طریق URIهای داده پشتیبانی می‌کند. تبدیل ویدیو به ویدیو به
    `runway/gen4_aleph` نیاز دارد. اجراهای فقط متنی نسبت‌های تصویر
    `16:9` و `9:16` را ارائه می‌کنند.
  </Accordion>
  <Accordion title="Together">
    فقط یک ارجاع تصویر.
  </Accordion>
  <Accordion title="Vydra">
    برای جلوگیری از تغییرمسیرهایی که احراز هویت را حذف می‌کنند، مستقیماً از
    `https://www.vydra.ai/api/v1` استفاده می‌کند. `veo3` فقط برای تبدیل متن به ویدیو ارائه
    شده است؛ `kling` به یک URL تصویر راه‌دور نیاز دارد.
  </Accordion>
  <Accordion title="xAI">
    مدل پیش‌فرض `grok-imagine-video` از تبدیل متن به ویدیو، تبدیل تک‌تصویرِ
    فریم نخست به ویدیو، حداکثر 7 ورودی `reference_image` از طریق
    `reference_images` متعلق به xAI، و جریان‌های ویرایش/تمدید ویدیوی راه‌دور پشتیبانی می‌کند. مقدار پیش‌فرض تولید
    `480P` است؛ اگر `aspectRatio` حذف شود، تبدیل تک‌تصویر به ویدیو نسبت منبع را
    به ارث می‌برد. ویرایش/تمدید ویدیو هندسهٔ ورودی را به ارث می‌برد و
    بازنویسی نسبت تصویر یا وضوح را نمی‌پذیرد. تمدید بین 2 تا 10
    ثانیه را می‌پذیرد.

    `grok-imagine-video-1.5` فقط برای تبدیل تصویر به ویدیو است: دقیقاً یک تصویر ارائه کنید.
    از 1 تا 15 ثانیه و `480P`، `720P` یا `1080P` پشتیبانی می‌کند و مقدار پیش‌فرض آن
    `480P` است؛ برای به ارث بردن نسبت تصویر منبع، `aspectRatio` را حذف کنید. شناسه‌های پیش‌نمایش
    و نسخهٔ تاریخ‌دار 1.5 با همان اعتبارسنجی مواجه می‌شوند و بدون تغییر
    ارسال می‌شوند.

  </Accordion>
</AccordionGroup>

## حالت‌های قابلیت ارائه‌دهنده

قرارداد مشترک تولید ویدیو به‌جای محدودیت‌های تجمیعی و یک‌دست، از قابلیت‌های
مختص هر حالت پشتیبانی می‌کند. پیاده‌سازی‌های جدید ارائه‌دهندگان
باید بلوک‌های صریح حالت را ترجیح دهند:

```typescript
capabilities: {
  generate: {
    maxVideos: 1,
    maxDurationSeconds: 10,
    supportsResolution: true,
  },
  imageToVideo: {
    enabled: true,
    maxVideos: 1,
    maxInputImages: 1,
    maxInputImagesByModel: { "provider/reference-to-video": 9 },
    maxDurationSeconds: 5,
  },
  videoToVideo: {
    enabled: true,
    maxVideos: 1,
    maxInputVideos: 1,
    maxDurationSeconds: 5,
  },
}
```

فیلدهای تجمیعی یک‌دست مانند `maxInputImages` و `maxInputVideos` برای اعلام
پشتیبانی از حالت تبدیل **کافی نیستند**. ارائه‌دهندگان باید
`generate`، `imageToVideo` و `videoToVideo` را صریحاً اعلام کنند تا آزمون‌های زنده،
آزمون‌های قرارداد و ابزار مشترک `video_generate` بتوانند پشتیبانی از حالت را
به‌صورت قطعی اعتبارسنجی کنند.

وقتی یک مدل در یک ارائه‌دهنده نسبت به بقیه از ورودی‌های ارجاع بیشتری پشتیبانی می‌کند،
به‌جای افزایش محدودیت کل حالت از `maxInputImagesByModel`، `maxInputVideosByModel` یا
`maxInputAudiosByModel` استفاده کنید.

## آزمون‌های زنده

پوشش زندهٔ اختیاری برای ارائه‌دهندگان مشترک همراه:

```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
```

پوشش‌دهندهٔ مخزن:

```bash
pnpm test:live:media video
```

این فایل زنده به‌طور پیش‌فرض پیش از پروفایل‌های احراز هویت ذخیره‌شده از متغیرهای محیطی
ازقبل صادرشدهٔ ارائه‌دهنده استفاده می‌کند و به‌طور پیش‌فرض یک آزمون دودِ امن برای انتشار اجرا می‌کند:

- `generate` برای هر ارائه‌دهندهٔ غیر FAL در پیمایش.
- درخواست یک‌ثانیه‌ای Lobster.
- سقف عملیات هر ارائه‌دهنده از
  `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (به‌طور پیش‌فرض `180000`).

FAL اختیاری است، زیرا تأخیر صف در سمت ارائه‌دهنده می‌تواند بر زمان انتشار
غلبه کند:

```bash
pnpm test:live:media video --video-providers fal
```

`OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` را تنظیم کنید تا حالت‌های تبدیل اعلام‌شده‌ای نیز اجرا شوند
که پیمایش مشترک می‌تواند با رسانهٔ محلی به‌طور امن آزمایش کند:

- `imageToVideo` وقتی `capabilities.imageToVideo.enabled`.
- `videoToVideo` وقتی `capabilities.videoToVideo.enabled` و
  ارائه‌دهنده/مدل ورودی ویدیوی محلی مبتنی بر بافر را در پیمایش مشترک می‌پذیرد.

در حال حاضر مسیر زندهٔ مشترک `videoToVideo` فقط زمانی `runway` را پوشش می‌دهد که
`runway/gen4_aleph` را انتخاب کنید.

## پیکربندی

مدل پیش‌فرض تولید ویدیو را در پیکربندی OpenClaw خود تنظیم کنید:

```json5
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-r2v-flash"],
      },
    },
  },
}
```

یا از طریق CLI:

```bash
openclaw config set agents.defaults.mediaModels.video.primary "qwen/wan2.6-t2v"
```

## مرتبط

- [Alibaba Model Studio](/fa/providers/alibaba)
- [کارهای پس‌زمینه](/fa/automation/tasks) - ردیابی کار برای تولید ناهمگام ویدیو
- [BytePlus](/fa/concepts/model-providers#byteplus-international)
- [ComfyUI](/fa/providers/comfy)
- [مرجع پیکربندی](/fa/gateway/config-agents#agent-defaults)
- [fal](/fa/providers/fal)
- [Google (Gemini)](/fa/providers/google)
- [MiniMax](/fa/providers/minimax)
- [مدل‌ها](/fa/concepts/models)
- [OpenAI](/fa/providers/openai)
- [Qwen](/fa/providers/qwen)
- [Runway](/fa/providers/runway)
- [Together AI](/fa/providers/together)
- [نمای کلی ابزارها](/fa/tools)
- [Vydra](/fa/providers/vydra)
- [xAI](/fa/providers/xai)
