API ساخت ویدیو با هوش مصنوعی: Veo 3.1، Kling و Seedance با پرداخت تومانی

اگر می‌خواهی در محصولت از روی یک جمله یا یک عکس، ویدیوی کوتاه بسازی (تیزر محصول، پس‌زمینهٔ متحرک، کلیپ عمودی برای استوری)، لازم نیست با چند پنل خارجی و چند کارت ارزی کلنجار بروی. با همان کلید sk-up-… و همان آدرس https://api.uttapen.ir/v1 که برای مدل‌های متنی استفاده می‌کنی، به مدل‌های ویدیویی مثل Veo 3.1 گوگل، Kling و Seedance هم می‌رسی. این راهنما روی سه چیز تمرکز دارد: ساخت ویدیو با API دقیقاً چطور کار می‌کند، کدام مدل برای کدام کار، و هزینه را چطور زیر کنترل نگه داری. کد آمادهٔ Python و curl هم داری.

چرا ساخت ویدیو با API از ایران سخت است

سازنده‌های اصلی مدل‌های ویدیویی هرکدام کنسول و صورت‌حساب جدای خودشان را دارند و اعتبار را به دلار و با کارت بین‌المللی می‌فروشند. یعنی اگر بخواهی Veo و Kling و Seedance را کنار هم امتحان کنی، باید چند حساب جدا بسازی، چند بار ارز بخری و چند نوع API متفاوت را یاد بگیری. از ایران، همان قدم اول یعنی پرداخت، معمولاً گیر می‌کند. مسیرهای دور زدنش (کارت مجازی، حساب یک آشنا) را در راهنمای دسترسی به API مدل‌ها از ایران بررسی کرده‌ایم.

در یوتاپن کیف پول تومانی است و با درگاه بانکی ایرانی شارژ می‌شود. همهٔ مدل‌های ویدیو پشت یک endpoint مشترک‌اند و فقط رشتهٔ model عوض می‌شود. آدرس API داخل ایران است و مسیر بین‌المللی درخواست را زیرساخت ما در خارج از ایران مدیریت می‌کند، پس VPN لازم نیست. فهرست کامل مدل‌ها و قیمت لحظه‌ای هرکدام در صفحهٔ مدل‌های ساخت ویدیو است.

ساخت ویدیو با API چطور کار می‌کند

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

1. ثبت کار: با POST /v1/videos مدل، متن درخواست و تنظیمات (مدت، رزولوشن، نسبت تصویر) را می‌فرستی. پاسخ همان لحظه می‌رسد: یک «کار» (job) با id و status برابر queued یا in_progress.
2. رزرو مبلغ: همان لحظه مبلغی موقت از کیف پول رزرو می‌شود و در فیلد hold_toman می‌بینی‌اش.
3. پیگیری: هر ۵ تا ۱۰ ثانیه GET /v1/videos/{id} را صدا می‌زنی. فیلد progress تخمینی از ۰ تا ۹۵ است.
4. تکمیل: وقتی status به completed رسید، outputs[].url و cost_toman پر شده‌اند و فقط هزینهٔ واقعی از رزرو کم می‌شود.
5. دانلود: outputs[0].url لینکی امضاشده و ۲۴ساعته است که بدون کلید باز می‌شود. می‌توانی فایل را با کلید از مسیر /v1/videos/{id}/content هم بگیری.

اگر کار شکست بخورد (failed)، error.code و پیامی فارسی برمی‌گردد و هیچ مبلغی کم نمی‌شود. اگر در مهلت ۶۰ دقیقه تمام نشود، وضعیت expired می‌شود و رزرو آزاد می‌شود. فایل‌ها ۳۰ روز روی سرور ما در ایران نگه داشته می‌شوند. جزئیات کامل همهٔ فیلدها در مستند ساخت ویدیو با API آمده.

Veo 3.1، Kling یا Seedance: کدام مدل ویدیو را انتخاب کنم

در کاتالوگ نزدیک به ۳۰ مدل ویدیویی هست. عدد بنچمارک یا رتبه‌بندی کیفیت نمی‌آوریم، چون کیفیت ویدیو خیلی به نوع صحنه بستگی دارد و باید روی نمونهٔ خودت بسنجی. جدول زیر از مشخصاتی ساخته شده که روی صفحهٔ هر مدل آمده:

چند نکته بر اساس توضیحی که خود سازنده‌ها روی صفحهٔ مدل نوشته‌اند:

Veo 3.1 برای خروجی نهایی. گوگل آن را برای خروجی نهایی با بالاترین کیفیت تصویر معرفی می‌کند؛ صدای هم‌زمان با تصویر هم می‌سازد. Veo 3.1 Fast تعادلی بین سرعت و کیفیت است و زودتر جواب می‌دهد، و Veo 3.1 Lite به گفتهٔ گوگل برای حجم بالا و آزمون‌وخطای سریع طراحی شده. هر سه فقط نسبت 16:9 و 9:16 را دارند.

Kling v3.0 برای کنترل فریم. هر دو نسخه متن به ویدیو و عکس به ویدیو را با کنترل فریم اول و آخر پشتیبانی می‌کنند و در انتخاب مدت دستت بازتر است. به گفتهٔ سازنده، کیفیت تصویر Pro از Standard بالاتر است.

Seedance 2.0 برای ثبات شخصیت و قاب‌های متنوع. ByteDance روی حفظ یکدستی شخصیت در طول ویدیو تأکید می‌کند. از متنوع‌ترین مدل‌ها در نسبت تصویر هم هست، از 21:9 تا 9:21. در نسخهٔ Fast اولویت با سرعت و هزینهٔ کمتر است و رزولوشن تا 720p می‌رود.

MiniMax H3 بیشتر برای ویرایش کنترل‌شده با دستور متنی معرفی شده، و Grok Imagine Video 1.5 بازهٔ مدت گسترده و نسبت‌های تصویر زیادی دارد ولی صدا نمی‌سازد.

اگر نمی‌دانی از کجا شروع کنی، model را uttapen/auto-video بگذار. یک مدل زبانی ارزان درخواستت را می‌خواند و برای متن به ویدیو، متحرک کردن عکس یا پیش‌نویس ارزان مدل مناسب را برمی‌دارد. دلیل انتخاب در پاسخ می‌آید و هزینهٔ همین تشخیص جدا گزارش می‌شود. این رفتار در مرور API رسانه توضیح داده شده.

تبدیل متن به ویدیو یا تبدیل عکس به ویدیو

اگر فقط prompt بفرستی، مدل صحنه را از صفر می‌سازد. ولی اگر عکس محصول، لوگو یا یک فریم مشخص داری، آن را در فیلد image بفرست (آدرس https یا data:image/…;base64) تا مدل همان را متحرک کند. در عمل این مسیر برای یکدست ماندن ظاهر محصول یا شخصیت قابل‌اعتمادتر است، چون نقطهٔ شروع را خودت تعیین کرده‌ای. مدل‌هایی که در جدول «تصویر اول و آخر» دارند، فیلد last_image را هم می‌پذیرند تا ویدیو بین دو فریمی که خودت داده‌ای ساخته شود؛ مثلاً از جعبهٔ دربسته تا جعبهٔ باز.

قیمت ساخت ویدیو با هوش مصنوعی چطور حساب می‌شود

قیمت ویدیو به‌ازای هر ثانیه است و به رزولوشن و روشن یا خاموش بودن صدا بستگی دارد. روی صفحهٔ بیشتر مدل‌ها یک جدول «قیمت هر حالت» هست که قیمت هر ثانیه را برای هر ترکیب نشان می‌دهد. مثلاً روی صفحهٔ Veo 3.1، حالت 4K و حالت با صدا هرکدام گران‌تر از حالت بی‌صدا با رزولوشن معمولی‌اند. در بعضی مدل‌ها، مثل Seedance، قیمت با کلمهٔ «حدود» آمده، چون هزینهٔ واقعی بعد از ساخت معلوم می‌شود.

عدد تومانی را اینجا نمی‌نویسیم، چون با نرخ دلار و قیمت سازنده روزانه عوض می‌شود. قیمت زنده را روی فهرست مدل‌های ویدیو (ارزان‌ترین حالت هر مدل) و صفحهٔ خود هر مدل ببین. منطق محاسبه این است:

• رزرو: مدت × قیمت هر ثانیه در همان رزولوشن و حالت صدا. اگر موجودی کافی نباشد، پیش از هر ساختی 402 insufficient_balance می‌گیری.
• تسویه: بعد از تکمیل، فقط هزینهٔ واقعی که سازندهٔ مدل گزارش می‌کند کم می‌شود و باقی رزرو برمی‌گردد. عددش در cost_toman همان شیء کار است.
• ساخت ناموفق رایگان است: خطا، رد شدن به‌خاطر قوانین محتوا، تمام نشدن در مهلت یا نرسیدن فایل، همه رزرو را کامل آزاد می‌کنند.

برای مقایسهٔ کلی هزینهٔ مدل‌های متنی و رسانه‌ای، مقالهٔ قیمت API مدل‌ها به تومان و صفحهٔ قیمت‌ها را هم ببین.

ساخت ویدیو با curl

ثبت کار با uttapen/auto-video و یک پرامپت فارسی:

curl https://api.uttapen.ir/v1/videos \
  -H "Authorization: Bearer sk-up-..." -H "Content-Type: application/json" \
  -d '{
    "model": "uttapen/auto-video",
    "prompt": "موج‌های دریا هنگام غروب، نمای هوایی آرام",
    "seconds": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

پاسخ همان شیء کار است. model در پاسخ نشان می‌دهد چه مدلی انتخاب شده و params تنظیمات نهایی را می‌گوید، از جمله generate_audio که پیش‌فرضش روشن است:

{ "id": "01a1043f-…", "object": "video", "status": "in_progress", "progress": 0, "model": "google/veo-3.1-fast",
  "params": { "seconds": 8, "resolution": "720p", "aspect_ratio": "16:9", "generate_audio": true },
  "hold_toman": "…", "cost_toman": null, "outputs": [], "error": null }

بعد از تکمیل، فایل را با کلید دانلود کن:

curl -L -o video.mp4 https://api.uttapen.ir/v1/videos/<id>/content -H "Authorization: Bearer sk-up-..."

اگر کار هنوز تمام نشده باشد، این مسیر 409 not_ready برمی‌گرداند.

ساخت و پیگیری ویدیو با Python

مثل نمونهٔ مستندات، اینجا با httpx و درخواست HTTP مستقیم کار می‌کنیم. این نمونه یک عکس را به ویدیوی عمودی تبدیل می‌کند، تا پایان کار صبر می‌کند و فایل را ذخیره می‌کند:

import time, httpx

H = {"Authorization": "Bearer sk-up-..."}
BASE = "https://api.uttapen.ir/v1"

r = httpx.post(f"{BASE}/videos", headers=H, json={
    "model": "bytedance/seedance-2.0-fast",
    "prompt": "دوربین آرام دور فنجان قهوه می‌چرخد، بخار بالا می‌رود",
    "image": "https://example.com/coffee.jpg",   # تصویر اول
    "seconds": 5,
    "resolution": "480p",
    "aspect_ratio": "9:16",
})
if r.is_error:                              # 400/402/429: پیام خطا را ببین
    raise SystemExit(r.text)
job_id = r.json()["id"]

while True:
    job = httpx.get(f"{BASE}/videos/{job_id}", headers=H).json()
    if job["status"] in ("completed", "failed", "expired"):
        break
    time.sleep(5)                           # هر ۵ تا ۱۰ ثانیه کافی است

print(job["status"], job["cost_toman"], job["error"])
if job["status"] == "completed":
    r = httpx.get(f"{BASE}/videos/{job_id}/content", headers=H, follow_redirects=True)
    open("video.mp4", "wb").write(r.content)

اگر مقداری بفرستی که مدل ندارد (مثلاً مدتی خارج از فهرست همان مدل)، پیش از هر رزروی 400 invalid_request می‌گیری و فیلد param نام همان فیلد و مقدارهای مجاز را می‌گوید. هم‌زمان حداکثر ۳ کار فعال می‌توانی داشته باشی و کار چهارم 429 too_many_active_jobs می‌گیرد. پس در صف‌های پرحجم، کارها را پشت سر هم بفرست. همهٔ کدهای خطای رسانه در مستند API رسانه فهرست شده‌اند.

پرامپت فارسی برای ساخت ویدیو

متن درخواست تا ۴٬۰۰۰ نویسه می‌تواند باشد و نمونهٔ خود مستندات هم پرامپت فارسی دارد. با این حال درک فارسی بین مدل‌ها لزوماً یکسان نیست و چند عادت ساده معمولاً نتیجه را قابل‌پیش‌بینی‌تر می‌کند:

• صحنه، حرکت و دوربین را جدا بگو. «یک فنجان قهوه روی میز چوبی، بخار آرام بالا می‌رود، دوربین آهسته به چپ می‌چرخد» بهتر از «ویدیوی قشنگ از قهوه» جواب می‌دهد.
• یک اتفاق در هر کلیپ. ویدیوهای چندثانیه‌ای برای یک حرکت اصلی مناسب‌اند. داستان چندمرحله‌ای را به چند کلیپ بشکن.
• متن روی تصویر را از مدل نخواه، مگر از مدلی که سازنده‌اش صریحاً رندر متن را ذکر کرده باشد. نوشتهٔ فارسی داخل ویدیو را بهتر است بعداً در تدوین اضافه کنی.
• اگر نتیجه از جزئیاتت دور شد، همان توصیف تصویری را یک بار هم به انگلیسی بفرست و دو نتیجه را کنار هم بگذار. روی مدل خودت بسنج؛ قاعدهٔ ثابتی نیست.
• برای تکرارپذیری seed بگذار تا وقتی فقط پرامپت را کمی تغییر می‌دهی، تفاوت از تصادف نباشد.

یادت باشد محتوای جنسی، خشونت شدید و تصویر یا صدای شبیه افراد واقعی ساخته نمی‌شود و چنین درخواستی پیش از هر هزینه‌ای با 400 content_policy_violation رد می‌شود.

کم کردن هزینهٔ ساخت ویدیو

چون قیمت ثانیه‌ای است، هر تصمیم روی مدت، رزولوشن و صدا مستقیم روی صورت‌حساب اثر دارد:

• اول کوتاه و کم‌رزولوشن. پرامپت را با کوتاه‌ترین مدت مدل و 480p یا 720p جا بینداز. وقتی صحنه همان شد که می‌خواستی، نسخهٔ نهایی را بلندتر یا با رزولوشن بالاتر بساز.
• نسخهٔ سریع برای پیش‌نویس. Veo 3.1 Lite و Fast یا Seedance 2.0 Fast برای آزمون‌وخطا ساخته شده‌اند. مدل گران‌تر را برای خروجی نهایی نگه دار.
• صدا را اگر لازم نداری خاموش کن. generate_audio پیش‌فرض روشن است و در مدل‌هایی مثل Veo 3.1 حالت با صدا قیمت ثانیهٔ بالاتری دارد. اگر بعداً موسیقی یا گوینده روی ویدیو می‌گذاری، "generate_audio": false بفرست؛ موسیقی پس‌زمینه را می‌توانی جدا با API ساخت موسیقی با هوش مصنوعی بسازی.
• هزینه را پیش از ساخت بسنج و سقف بگذار. مدت × قیمت هر ثانیهٔ همان حالت (از صفحهٔ مدل) را با بودجه‌ات مقایسه کن و بعد از ثبت، hold_toman پاسخ را ببین. در کدت هم برای مدت و رزولوشن سقف بگذار تا کاربر نهایی نتواند ناخواسته کلیپ 4K بیست‌ثانیه‌ای سفارش دهد.
• فایل را زود بردار. لینک‌ها ۲۴ ساعته و فایل‌ها ۳۰ روزه‌اند. اگر خروجی را لازم داری، روی سرور خودت ذخیره‌اش کن تا مجبور به ساخت دوباره نشوی.

بدون کد: استودیوی یوتاپن

اگر هم‌تیمی‌ات برنامه‌نویس نیست، یا خودت می‌خواهی پیش از نوشتن کد چند مدل را مقایسه کنی، استودیوی تصویر و ویدیو همین کارها را در مرورگر انجام می‌دهد. یک جمله می‌نویسی، استودیو مدل مناسب را خودش انتخاب می‌کند، پیش از ساخت قیمت را نشانت می‌دهد و بعد از ساخت فقط هزینهٔ واقعی را کم می‌کند. پرامپتی را که در استودیو جواب داد، بعداً عیناً در API به کار ببر.

پرسش‌های پرتکرار

API ساخت ویدیو با هوش مصنوعی هم‌زمان جواب می‌دهد؟

نه. POST /v1/videos فوراً شناسهٔ کار را برمی‌گرداند و ویدیو پشت صحنه ساخته می‌شود. با GET /v1/videos/{id} هر چند ثانیه وضعیت را می‌پرسی تا به completed، failed یا expired برسد.

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

نه. در شکست، رد شدن به‌خاطر قوانین محتوا، منقضی شدن در مهلت ۶۰ دقیقه یا نرسیدن فایل، کل مبلغ رزروشده به کیف پول برمی‌گردد.

قیمت هر ثانیه ویدیو را کجا ببینم؟

روی صفحهٔ هر مدل قیمت هر ثانیه آمده و در بیشتر مدل‌ها جدول «قیمت هر حالت» آن را برای هر رزولوشن و حالت صدا جدا نشان می‌دهد. فهرست مدل‌های ویدیو هم ارزان‌ترین حالت هر مدل را کنار هم می‌گذارد. هزینهٔ دقیق هر کار بعد از تکمیل در cost_toman می‌آید.

حداکثر طول ویدیو چقدر است؟

در API تا ۲۰ ثانیه، ولی مقدار seconds باید یکی از مدت‌هایی باشد که خود مدل پشتیبانی می‌کند و روی صفحه‌اش آمده؛ مثلاً Veo 3.1 فقط ۴، ۶ و ۸ ثانیه را می‌پذیرد. اگر seconds را نفرستی، ۵ ثانیه یا کوتاه‌ترین مدت مدل انتخاب می‌شود.

می‌توانم عکس خودم را به ویدیو تبدیل کنم؟

بله. عکس را در فیلد image بفرست تا فریم اول ویدیو باشد. مدل‌هایی مثل Veo 3.1، Kling v3.0 و Seedance 2.0 تصویر آخر (last_image) را هم می‌پذیرند.

برای Veo 3.1 یا Kling باید کتابخانهٔ جدا نصب کنم؟

نه. همهٔ مدل‌های ویدیو با یک endpoint و یک قالب درخواست کار می‌کنند و فقط مقدار model عوض می‌شود. یک درخواست HTTP ساده با هر زبانی کافی است.

جمع‌بندی

برای اضافه کردن ساخت ویدیو به محصولت، یک کلید sk-up-… و یک حلقهٔ ساده برای پیگیری کار کافی است. با uttapen/auto-video یا یک مدل سریع و کلیپ کوتاه کم‌رزولوشن شروع کن، و وقتی پرامپت جا افتاد، سراغ Veo 3.1 یا Seedance 2.0 با کیفیت نهایی برو. اگر می‌خواهی اول بدون کد امتحان کنی، از استودیو شروع کن؛ برای کار با API، مستند ساخت ویدیو را باز کن و اولین کار را ثبت کن.