تولید ویدیو با 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" } ]}پارامترهای درخواست
| پارامتر | الزامی | نوع | توضیحات |
|---|---|---|---|
| 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 | خیر | string | 16: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 حدود ۳۰ ثانیه طول کشید و کلیپهای بلندتر یا باکیفیتتر بیشتر.
| فیلد | نوع | توضیح |
|---|---|---|
| id | string | شناسهٔ کار، با پیشوند video_. |
| object | string | همیشه video. |
| status | string | queued، in_progress، completed یا failed. |
| progress | int | درصد تقریبی پیشرفت (۰ تا ۱۰۰). |
| polling_url | string | نشانی کامل برای پرسش وضعیت. |
| seconds / size / resolution / aspect_ratio | مقدار | مقادیری که واقعاً اعمال شد (پیشفرضها پر شدهاند). seconds رشته است، مثل "4". |
| created_at | unix | زمان ثبت درخواست. |
| generate_audio | bool | آیا برای ویدیو صدا ساخته میشود. |
| usage.cost_rial / charged_rial | int | هزینه و مبلغی که از کیف پول کم شد (ریال). |
| usage.refunded_rial | int | مبلغ بازگشتی؛ برای کار ناموفق برابر هزینه میشود. |
| unsigned_urls | string[] | فقط در completed: نشانی دانلود از خود هیبانا (/content?index=0). نیاز به کلید API دارد. |
| urls | string[] | فقط در completed: لینک مستقیم فایل. بدون کلید باز میشود، پس آن را خصوصی بدانید و منتشر نکنید. |
| expires_at / completed_at | unix | فقط در 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میآید. اگر موجودی کافی نباشد، پیش از هر کاری 402insufficient_fundsمیگیرید. - اگر ساخت شکست بخورد، همهٔ مبلغ خودکار برمیگردد و در
usage.refunded_rialدیده میشود. اگر ارائهدهنده در دسترس نباشد (503) اصلاً چیزی کم نمیشود. - قیمتها تخفیف مدل را هم دارند؛ قیمت اصلی و تخفیفخورده در صفحهٔ مدل کنار هم نشان داده میشود. توضیح کلی در قیمتگذاری.
خطاها
| HTTP | کد | معنی |
|---|---|---|
| 402 | insufficient_funds | موجودی کیف پول برای قیمت این ویدیو کافی نیست. پیام خطا قیمت ویدیو را میگوید. |
| 402 | budget_exceeded | سقف هزینهٔ کلید API پر شده است. |
| 429 | concurrency_limit | بیش از ۴ ویدیو همزمان در حال ساخت است. هدر Retry-After برابر ۳۰ ثانیه. |
| 400 | byok_not_supported | کلیدهای BYOK نمیتوانند ویدیو بسازند. |
| 400 | unknown_parameter | فیلدی فرستادهاید که API نمیشناسد. |
| 400 | unsupported_parameter | callback_url، previous_job_id، provider و n پشتیبانی نمیشوند. |
| 400 | video_model_requires_videos_endpoint | مدل ویدیو را به chat/completions فرستادهاید؛ از /v1/videos استفاده کنید. |
| 400 | کدهای اعتبارسنجی | مقدار نامعتبر برای duration، resolution و مانند آن. فیلد param مشخص میکند کدام فیلد. |
| 409 | video_not_ready | فایل را پیش از completed شدن خواستهاید. |
| 410 | video_expired | یک ساعت از ساخت گذشته و فایل پاک شده است. |
| 503 | provider_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 میگیرید؛ ۳۰ ثانیه صبر کنید یا یکی تمام شود.