رفتن به محتوا

تولید ویدیو با AI

ساخت ویدیو از متن یا تصویر با یک API ناهمگام: ارسال، پرسش وضعیت، دانلود

مستندات

سه مرحله

ساخت ویدیو چند ده ثانیه تا چند دقیقه طول می‌کشد، پس برخلاف چت، پاسخ در همان درخواست نمی‌آید. API ناهمگام است و با قالب OpenRouter سازگار است: کار را می‌سپارید، پیشرفتش را می‌پرسید و در پایان فایل را می‌گیرید. نشانی پایه https://api-ai.hibanacloud.ir/v1 و کلید همان کلید API چت شماست.

مراحل ساخت ویدیو
مرحلهچه می‌کنید
۱. ارسالPOST /v1/videos را با مدل و prompt می‌فرستید (JSON، یا multipart مثل SDKهای OpenAI). بلافاصله پاسخ 200 با یک شناسه می‌گیرید و هزینه از کیف پول کم می‌شود.
۲. پرسش وضعیتGET /v1/videos/{id} را هر ۵ تا ۱۰ ثانیه صدا بزنید تا وضعیت completed یا failed شود.
۳. دانلودGET /v1/videos/{id}/content فایل MP4 را با همان کلید API برمی‌گرداند. فایل تا یک ساعت پس از ساخت پاک می‌شود.

هزینهٔ ویدیو هنگام ارسال از کیف پول کم می‌شود و اگر ساخت شکست بخورد خودکار برمی‌گردد. فایل کمتر از یک ساعت پس از ساخت از سرور پاک می‌شود؛ پس از completed شدن همان موقع دانلودش کنید و در فضای خودتان نگه دارید.

متن به ویدیو

نمونهٔ زیر هر سه مرحله را انجام می‌دهد: ارسال، پرسش وضعیت تا پایان، و ذخیرهٔ فایل در video.mp4. نمونه‌های Python، Node.js، C# و Java با SDK رسمی OpenAI نوشته شده‌اند (بخش videos همان SDK، فقط base_url را عوض کنید) و همه پیش از انتشار اجرا و آزمایش شده‌اند. این نمونه‌ها پول واقعی خرج می‌کنند (یک کلیپ ۴ ثانیه‌ای 360p)، پس قبل از اجرا قیمت مدل را در صفحهٔ آن ببینید.

KEY="YOUR_API_KEY"BASE="https://api-ai.hibanacloud.ir/v1" # ۱) ثبت درخواست (مبلغ همین حالا کم می‌شود و اگر ویدیو ساخته نشود خودکار برمی‌گردد)ID=$(curl -s "$BASE/videos" \  -H "Authorization: Bearer $KEY" \  -H "Content-Type: application/json" \  -d '{"model": "google/gemini-omni-1.2-flash", "prompt": "A red paper boat drifting on a calm pond at sunrise, static camera.", "seconds": "4", "size": "640x360"}' \  | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)echo "job: $ID" # ۲) صبر تا پایان ساختwhile true; do  STATUS=$(curl -s "$BASE/videos/$ID" -H "Authorization: Bearer $KEY" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)  echo "status: $STATUS"  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then break; fi  sleep 5done # ۳) دانلود فایل MP4 (تا یک ساعت پس از ساخت نگه داشته می‌شود)curl -s -o video.mp4 "$BASE/videos/$ID/content" -H "Authorization: Bearer $KEY"

پاسخ ارسال (HTTP 200) چنین است:

{  "id": "video_01J...",  "object": "video",  "model": "google/gemini-omni-1.2-flash",  "status": "queued",  "progress": 0,  "created_at": 1794652173,  "seconds": "4",  "size": "640x360",  "resolution": "360p",  "aspect_ratio": "16:9",  "generate_audio": true,  "polling_url": "https://api-ai.hibanacloud.ir/v1/videos/video_01J...",  "usage": { "cost_rial": 0, "charged_rial": 0, "refunded_rial": 0, "seconds": 4, "resolution": "360p" }}

تصویر به ویدیو

برای متحرک کردن یک عکس، آن را قاب اول ویدیو کنید: در SDKهای OpenAI و cURL به‌صورت فایل در input_reference، یا در JSON به‌صورت frame_images (data URI یا نشانی https که خود هیبانا دانلود می‌کند). قالب‌ها PNG، JPEG و WebP تا ۸ مگابایت‌اند. نمونهٔ زیر start.png را می‌خواند.

KEY="YOUR_API_KEY"BASE="https://api-ai.hibanacloud.ir/v1" # ۱) ثبت درخواست؛ عکس start.png قاب اول ویدیو است (PNG / JPEG / WebP، حداکثر ۸ مگابایت)ID=$(curl -s "$BASE/videos" \  -H "Authorization: Bearer $KEY" \  -F model="google/gemini-omni-1.2-flash" \  -F prompt="The camera slowly pushes in as the scene starts to move." \  -F seconds=4 \  -F size=640x360 \  -F input_reference=@start.png | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)echo "job: $ID" # ۲) صبر تا پایان ساختwhile true; do  STATUS=$(curl -s "$BASE/videos/$ID" -H "Authorization: Bearer $KEY" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)  echo "status: $STATUS"  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then break; fi  sleep 5done # ۳) دانلود فایل MP4 (تا یک ساعت پس از ساخت نگه داشته می‌شود)curl -s -o video.mp4 "$BASE/videos/$ID/content" -H "Authorization: Bearer $KEY"

قاب اول و آخر (گذار)

اگر هم first_frame و هم last_frame بدهید، مدل گذار بین دو تصویر را می‌سازد. مقدار frame_type هر عنصر مشخص می‌کند کدام قاب است:

{  "model": "google/gemini-omni-1.2-flash",  "prompt": "a smooth transition from day to night over the city",  "duration": 5,  "resolution": "720p",  "frame_images": [    {      "type": "image_url",      "image_url": { "url": "https://example.com/city-day.png" },      "frame_type": "first_frame"    },    {      "type": "image_url",      "image_url": { "url": "data:image/png;base64,<Base64 تصویر شب>" },      "frame_type": "last_frame"    }  ]}

پارامترهای درخواست

پارامترهای POST /v1/videos
پارامترالزامینوعتوضیحات
modelبلهstringکد مدل ویدیو، مثل google/gemini-omni-1.2-flash.
promptبله*stringتوضیح صحنه، تا ۸۰۰۰ نویسه. اگر first_frame فرستاده‌اید می‌تواند خالی باشد.
secondsخیرstring / intطول ویدیو به ثانیه، مثل "4" (نام دیگر: duration). پیش‌فرض: پیش‌فرض مدل، وگرنه ۸ ثانیه.
resolutionخیرstringیکی از 360p، 720p، 1080p، 4K (بسته به مدل). پیش‌فرض: پیش‌فرض مدل، وگرنه 720p.
aspect_ratioخیرstring16:9 یا 9:16. پیش‌فرض: پیش‌فرض مدل، وگرنه 16:9.
sizeخیرstringجایگزین resolution و aspect_ratio، مثل 640x360 (360p) یا 1280x720 (720p).
input_referenceخیرfile / objectقالب SDKهای OpenAI: فایل تصویر (یا {image_url}) که قاب اول ویدیو می‌شود.
frame_imagesخیرarrayتصویر قاب اول و آخر (تصویر به ویدیو). ساختار در بخش بعد آمده است.
input_referencesخیرarrayتصویرهای مرجع؛ فقط اگر مدل اجازه بدهد.
generate_audioخیرboolساخت صدا. پیش‌فرض true وقتی مدل صدا می‌سازد. برخی مدل‌ها مثل Gemini Omni همیشه صدا می‌سازند و false را نمی‌پذیرند.
seedخیرintبرای نتیجهٔ تکرارپذیرتر.

* prompt فقط وقتی می‌تواند خالی باشد که first_frame فرستاده باشید. فیلد ناشناس با unknown_parameter رد می‌شود. هدر اختیاری Idempotency-Key را برای جلوگیری از ساخت (و پرداخت) دوباره در تلاش مجدد بفرستید؛ توضیحش در کلید یکتایی است.

پاسخ و وضعیت‌ها

GET https://api-ai.hibanacloud.ir/v1/videos/{id} همان شیء ارسال را با status به‌روز برمی‌گرداند (queued، سپس in_progress، و در پایان completed یا failed). هر ۵ تا ۱۰ ثانیه بپرسید؛ در آزمایش ما یک کلیپ ۴ ثانیه‌ای 360p حدود ۳۰ ثانیه طول کشید و کلیپ‌های بلندتر یا باکیفیت‌تر بیشتر.

فیلدهای پاسخ
فیلدنوعتوضیح
idstringشناسهٔ کار، با پیشوند video_.
objectstringهمیشه video.
statusstringqueued، in_progress، completed یا failed.
progressintدرصد تقریبی پیشرفت (۰ تا ۱۰۰).
polling_urlstringنشانی کامل برای پرسش وضعیت.
seconds / size / resolution / aspect_ratioمقدارمقادیری که واقعاً اعمال شد (پیش‌فرض‌ها پر شده‌اند). seconds رشته است، مثل "4".
created_atunixزمان ثبت درخواست.
generate_audioboolآیا برای ویدیو صدا ساخته می‌شود.
usage.cost_rial / charged_rialintهزینه و مبلغی که از کیف پول کم شد (ریال).
usage.refunded_rialintمبلغ بازگشتی؛ برای کار ناموفق برابر هزینه می‌شود.
unsigned_urlsstring[]فقط در completed: نشانی دانلود از خود هیبانا (/content?index=0). نیاز به کلید API دارد.
urlsstring[]فقط در completed: لینک مستقیم فایل. بدون کلید باز می‌شود، پس آن را خصوصی بدانید و منتشر نکنید.
expires_at / completed_atunixفقط در completed: زمان پاک شدن فایل (کمتر از یک ساعت پس از ساخت) و زمان پایان.
error / refundedمقدارفقط در failed: error به شکل {code, message} و refunded: true.

وقتی کار تمام شد (status برابر completed):

{  "id": "video_01J...",  "status": "completed",  "progress": 100,  "unsigned_urls": ["https://api-ai.hibanacloud.ir/v1/videos/video_01J.../content?index=0"],  "urls": ["https://blob.hibanacloud.ir/hibana-ai/videos/....mp4"],  "expires_at": 1794655495,  "completed_at": 1794652195}

برای گرفتن فایل از unsigned_urls[0] با هدر Authorization استفاده کنید (پاسخ video/mp4 است)، یا لینک مستقیم urls[0] را که کلید نمی‌خواهد. لینک مستقیم را برای خودتان نگه دارید و در جایی عمومی نگذارید. اگر وضعیت failed شد، مبلغ خودکار به کیف پول برمی‌گردد (refunded: true) و علت در error.message است.

مدل‌ها و قابلیت‌ها

مدل‌های ویدیو در فهرست مدل‌ها با دستهٔ «ویدیو» هستند و صفحهٔ هر مدل قیمت هر ثانیه به تفکیک کیفیت، طول‌های مجاز، کیفیت‌ها، نسبت‌های تصویر و انواع قاب را نشان می‌دهد. همین اطلاعات را با کلید API هم می‌توانید بخوانید:

GET https://api-ai.hibanacloud.ir/v1/videos/models

هر عنصر شامل supported_durations، supported_resolutions، supported_aspect_ratios، supported_frame_images، max_input_references، generate_audio_optional (اگر false باشد مدل همیشه صدا می‌سازد و generate_audio: false پذیرفته نمی‌شود)، مقادیر پیش‌فرض و بخش pricing (به ریال برای هر ثانیه، با کلید per_second_without_audio وقتی نسخهٔ بی‌صدا ارزان‌تر است) است.

هزینه و بازگشت پول

  • قیمت = تعداد ثانیه × قیمت هر ثانیهٔ همان کیفیت. مثلاً یک کلیپ ۳ ثانیه‌ای در 720p برابر ۳ برابر قیمت ثانیهٔ 720p آن مدل است. کیفیت بالاتر ثانیهٔ گران‌تری دارد.
  • مبلغ هنگام ارسال از کیف پول کم می‌شود و در usage.charged_rial می‌آید. اگر موجودی کافی نباشد، پیش از هر کاری 402 insufficient_funds می‌گیرید.
  • اگر ساخت شکست بخورد، همهٔ مبلغ خودکار برمی‌گردد و در usage.refunded_rial دیده می‌شود. اگر ارائه‌دهنده در دسترس نباشد (503) اصلاً چیزی کم نمی‌شود.
  • قیمت‌ها تخفیف مدل را هم دارند؛ قیمت اصلی و تخفیف‌خورده در صفحهٔ مدل کنار هم نشان داده می‌شود. توضیح کلی در قیمت‌گذاری.

خطاها

خطاهای API ویدیو
HTTPکدمعنی
402insufficient_fundsموجودی کیف پول برای قیمت این ویدیو کافی نیست. پیام خطا قیمت ویدیو را می‌گوید.
402budget_exceededسقف هزینهٔ کلید API پر شده است.
429concurrency_limitبیش از ۴ ویدیو هم‌زمان در حال ساخت است. هدر Retry-After برابر ۳۰ ثانیه.
400byok_not_supportedکلیدهای BYOK نمی‌توانند ویدیو بسازند.
400unknown_parameterفیلدی فرستاده‌اید که API نمی‌شناسد.
400unsupported_parametercallback_url، previous_job_id، provider و n پشتیبانی نمی‌شوند.
400video_model_requires_videos_endpointمدل ویدیو را به chat/completions فرستاده‌اید؛ از /v1/videos استفاده کنید.
400کدهای اعتبارسنجیمقدار نامعتبر برای duration، resolution و مانند آن. فیلد param مشخص می‌کند کدام فیلد.
409video_not_readyفایل را پیش از completed شدن خواسته‌اید.
410video_expiredیک ساعت از ساخت گذشته و فایل پاک شده است.
503provider_unavailableارائه‌دهنده در دسترس نیست. هیچ مبلغی کم نشده؛ کمی بعد دوباره امتحان کنید.

شکل کلی پاسخ خطا و سیاست تلاش مجدد در مدیریت خطاها آمده است.

محدودیت‌ها

محدودیت‌های تولید ویدیو
موردمحدودیت
هم‌زمانیحداکثر ۴ ویدیو هم‌زمان در حال ساخت برای هر کاربر؛ بیشتر از آن 429 concurrency_limit.
تصویر ورودیPNG، JPEG یا WebP تا ۸ مگابایت. data URI یا نشانی https؛ نشانی را خود هیبانا دانلود می‌کند.
promptحداکثر ۸۰۰۰ نویسه.
نگهداری فایلکمتر از یک ساعت پس از ساخت پاک می‌شود. بعد از آن 410 video_expired.
کلیدکلید BYOK پذیرفته نمی‌شود.

چرا نه Chat Completions

مدل ویدیو را به chat/completions نفرستید. این مدل‌ها متن تولید نمی‌کنند و درخواست چت به آن‌ها با خطای 400 video_model_requires_videos_endpoint رد می‌شود (به‌جای پاسخ خالی). همیشه از /v1/videos استفاده کنید.

اگر می‌خواهید یک ویدیو را به مدل بدهید تا ببیند، آن بحث دیگری است: ورودی ویدیو.

پرسش‌های متداول

چرا ویدیو در همان درخواست برنمی‌گردد؟

ساخت ویدیو زمان‌بر است. درخواست را می‌سپارید، شناسه می‌گیرید و با پرسش وضعیت منتظر می‌مانید. callback_url و webhook پشتیبانی نمی‌شود، پس باید پرسش وضعیت را خودتان بزنید.

اگر ساخت شکست بخورد پولم چه می‌شود؟

کل مبلغ خودکار به کیف پول برمی‌گردد و در پاسخ refunded: true می‌بینید.

فایل تا کی می‌ماند؟

کمتر از یک ساعت پس از ساخت. پس از آن دانلود با 410 رد می‌شود؛ فایل را همان موقع در فضای خودتان ذخیره کنید.

با SDK رسمی OpenAI کار می‌کند؟

بله. client.videos.create، retrieve، poll و download_content با همان کد (فقط base_url هیبانا و کد مدل) کار می‌کنند. Python ممکن است هشدار منسوخ شدن API ویدیوی OpenAI (Sora) را چاپ کند که به هیبانا ربطی ندارد. برای Go و PHP فعلاً نمونه نداریم؛ با همان درخواست‌های HTTP نمونهٔ cURL کار کنید.

می‌توانم با کلید BYOK ویدیو بسازم؟

نه، BYOK برای ویدیو پشتیبانی نمی‌شود (400 byok_not_supported).

چند ویدیو را هم‌زمان می‌شود ساخت؟

تا ۴ ویدیو. از آن بیشتر 429 می‌گیرید؛ ۳۰ ثانیه صبر کنید یا یکی تمام شود.