ساخت ویدیو با API (videos)

ساخت ویدیوی غیرهم‌زمان با POST /v1/videos، پیگیری وضعیت با GET /v1/videos/{id} و دانلود خروجی: مدت، رزولوشن، صدا، تصویر اول و نحوهٔ محاسبهٔ قیمت هر ثانیه.

ساخت ویدیو چند ده ثانیه تا چند دقیقه طول می‌کشد، برای همین غیرهم‌زمان است: درخواست را می‌فرستی، شناسهٔ کار را می‌گیری، وضعیت را می‌پرسی و بعد از تکمیل فایل را دانلود می‌کنی.

۱. ثبت کار

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"
  }'

پاسخ همان شیء کار است با status برابر queued یا in_progress:

{ "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": "266915.000000", "cost_toman": null, "outputs": [], "error": null }

۲. پیگیری

import time, httpx

H = {"Authorization": "Bearer sk-up-..."}
job_id = "01a1043f-..."
while True:
    job = httpx.get(f"https://api.uttapen.ir/v1/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"])

`status`	یعنی
`queued` / `in_progress`	در حال ساخت؛ `progress` تخمینی از ۰ تا ۹۵
`completed`	آماده؛ `outputs[].url` و `cost_toman` پر شده
`failed`	شکست خورد؛ `error.code` و `error.message` فارسی؛ هیچ مبلغی کم نشد
`expired`	در مهلت (۶۰ دقیقه) تمام نشد؛ رزرو آزاد شد

۳. دانلود

outputs[0].url لینک امضاشدهٔ ۲۴ ساعته است و بدون کلید باز می‌شود. یا با کلید مستقیم بگیر:

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

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

فیلدها

فیلد	توضیح
`model`	شناسهٔ مدل یا `uttapen/auto-video`
`prompt`	متن درخواست، حداکثر ۴٬۰۰۰ نویسه
`seconds` (یا `duration`)	مدت؛ باید یکی از مدت‌های همان مدل باشد (در صفحهٔ مدل آمده)، حداکثر ۲۰ ثانیه؛ خالی یعنی ۵ ثانیه یا کوتاه‌ترین مدت
`resolution`	مثل `480p`، `720p`، `1080p`؛ خالی یعنی ۷۲۰p اگر مدل دارد
`aspect_ratio`	مثل `16:9`، `9:16`، `1:1`
`generate_audio`	برای مدل‌هایی که صدا می‌سازند؛ پیش‌فرض روشن
`image`	تصویر اول (آدرس `https` یا `data:image/…;base64`) برای متحرک کردن یک عکس
`last_image`	تصویر آخر، برای مدل‌هایی که دارند
`seed`	عدد ثابت برای تکرارپذیری

مقدار نامعتبر پیش از هر رزروی 400 invalid_request با param همان فیلد و فهرست مقدارهای مجاز می‌دهد.

قیمت

قیمت ویدیو به‌ازای هر ثانیه است و به رزولوشن و صدا بستگی دارد؛ جدول هر مدل در مدل‌های ویدیو. رزرو = مدت × قیمت ثانیهٔ همان حالت؛ بعد از تکمیل، هزینهٔ واقعی گزارش‌شده کم می‌شود. اگر ساخت شکست بخورد، منقضی شود یا فایل دانلود نشود، کل رزرو برمی‌گردد. جزئیات بیشتر در مرور رسانه.