ورودی ویدیو (Video Input)

فرستادن یک کلیپ ویدئویی همراه با پیام، تا مدل آن را ببیند و پاسخ بگوید

مستندات

کدام مدل‌ها ویدیو می‌پذیرند

ورودی ویدیو فقط روی مدل‌هایی کار می‌کند که قابلیت «ورودی ویدیو» دارند. فرستادن video_url به مدل‌های دیگر با خطای video_input_not_supported رد می‌شود. فهرست زیر مستقیم از کاتالوگ مدل‌ها خوانده می‌شود و همیشه به‌روز است:

در حال بارگذاری فهرست مدل‌ها… فهرست به‌روز همیشه در لیست مدل‌ها با فیلتر «ورودی ویدیو» هست، جایی که قیمت‌ها هم کنارش است.

ساختار content

فقط Base64، نشانی https پذیرفته نمی‌شود. برخلاف ورودی تصویر و ورودی فایل که یک نشانی عمومی را هم می‌پذیرند و خودشان دانلودش می‌کنند، ویدیو فقط به شکل data URI می‌آید، دقیقاً مثل ورودی صوت. یک نشانی فرستادن، از جمله لینک یوتیوب، با unsupported_attachment رد می‌شود.

مثل تصویر، فایل و صوت، content از یک رشتهٔ ساده به آرایه‌ای از «بخش»ها تبدیل می‌شود:

بخش‌های آرایهٔ content
نوع بخش	فیلد داده	توضیح
type: "text"	text	متن پیام کاربر، در همان بخش کنار ویدیو.
type: "video_url"	video_url.url	خود کلیپ ویدئویی: یک data URI با Base64 (مثل data:video/mp4;base64,...). نشانی https پذیرفته نمی‌شود.

{  "type": "video_url",  "video_url": {    "url": "data:video/mp4;base64,<Base64 کلیپ ویدئویی>"  }}

بقیهٔ درخواست تغییری نمی‌کند: همان model، همان messages، همان پارامترهای Chat Completions. حداکثر ۲ بخش video_url در یک درخواست جا می‌شود؛ بیشتر از آن با too_many_attachments رد می‌شود.

نمونه‌کد

فایل ویدئویی را بخوانید، Base64 کنید، و در یک بخش video_url بگذارید. به‌جای مدل نمونه، هر مدلی از فهرست بالا را می‌توانید بگذارید.

# ویدیو باید Base64 باشد؛ نشانی https پذیرفته نمی‌شود (حتی یوتیوب).VIDEO=$(base64 -w0 video.mp4) curl https://api-ai.hibanacloud.ir/v1/chat/completions \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-2.5-flash",    "messages": [{      "role": "user",      "content": [        {"type": "text", "text": "این ویدیو دربارهٔ چیست؟ در یک جمله بگو."},        {          "type": "video_url",          "video_url": {"url": "data:video/mp4;base64,'"$VIDEO"'"}        }      ]    }],    "max_completion_tokens": 1000  }'

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

فرمت‌های پذیرفته‌شده
MIME	پسوند
video/mp4	.mp4
video/mpeg	.mpeg / .mpg
video/quicktime	.mov (به‌صورت video/mov هم پذیرفته می‌شود)
video/webm	.webm

محدودیت‌های ورودی ویدیو
محدودیت	توضیح
حجم	۲۰ مگابایت برای هر کلیپ، پس از رمزگشایی از Base64 (نه حجم رشتهٔ Base64 خام).
تعداد	حداکثر ۲ ویدیو در یک درخواست.
فقط Base64	نشانی https پذیرفته نمی‌شود؛ حتی نشانی یوتیوب هم رد می‌شود. فقط data URI.
مدل	فقط مدل‌هایی با قابلیت «ورودی ویدیو» (فهرست بالا)؛ روی مدل دیگری خطای video_input_not_supported برمی‌گردد.

روی endpoint دیگر

همین قابلیت روی /v1/responses هم کار می‌کند، اما با شکل کمی متفاوت. برخلاف صوت که دقیقاً همان بخش را روی هر دو endpoint می‌پذیرد، اینجا نوع بخش input_video است، نه video_url:

{  "type": "input_video",  "video_url": "data:video/mp4;base64,<Base64 کلیپ ویدئویی>"}

فیلد video_url در اینجا یک رشتهٔ ساده است، ولی شکل شیءِ {"video_url": {"url": "..."}} هم پذیرفته می‌شود اگر ترجیح می‌دهید همان ساختار Chat Completions را نگه دارید.

هزینه

ویدیو نرخ جداگانه ندارد. برخلاف صوت که به نرخ ورودی صوت خودش حساب می‌شود، ویدیو مثل متن معمولی با همان نرخ ورودی عادی مدل حساب‌وکتاب می‌شود، نه با نرخ جدا.

تعداد توکن یک کلیپ به مدل، طول کلیپ و کیفیت تصویر بستگی دارد و بین مدل‌ها می‌تواند چند برابر فرق کند. عدد دقیق هر درخواست در usage.prompt_tokens پاسخ برمی‌گردد، مثل همیشه.

بعضی مدل‌ها صدای همراه کلیپ را جداگانه به‌عنوان توکن صوت حساب می‌کنند؛ آن بخش به نرخ ورودی صوت همان مدل قیمت می‌خورد؛ همان نرخی که ورودی صوت توضیح داده. بقیهٔ prompt با نرخ معمول ورودی حساب می‌شود.

توضیح کلی محاسبهٔ هزینه در قیمت‌گذاری.

خطاها و رفع اشکال

خطاهای مخصوص ورودی ویدیو
کد	معنی
video_input_not_supported	مدل انتخاب‌شده ویدیو نمی‌پذیرد؛ از جدول بالا یک مدل بردارید.
video_too_large	کلیپ پس از رمزگشایی از ۲۰ مگابایت بزرگ‌تر است.
unsupported_video_type	فرمت جزو فهرست فرمت‌های پذیرفته‌شده نیست.
invalid_video	رمزگشایی Base64 شکست خورد یا داده خراب است.

فهرست کامل خطاها و معنی هرکدام در مدیریت خطاها آمده است. اگر کد خطا ندارید ولی نتیجه درست نیست، از حل مشکلات شروع کنید.