پرش به محتوا

ساخت ویدیو

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

بازبینی: ۸ مهر ۱۴۰۵ ۶ دقیقه مطالعه

با POST /videos از روی توصیف متنی یک کلیپ کوتاه با صدا می‌سازید. ساختن ویدیو یک تا چند دقیقه طول می‌کشد، پس این endpoint بر خلاف بقیه فایل را همان لحظه برنمی‌گرداند: یک «کار» (Job) با شناسهٔ vid_… می‌سازد، شما وضعیتش را می‌پرسید و وقتی آماده شد فایل را می‌گیرید.

سه مرحله#

  1. ساختن کار

    POST /videos با مدل، توصیف، مدت و اندازه. پاسخ شیء کار است با status: "queued".

  2. پرسیدن وضعیت

    GET /videos/{id} هر ۱۰ تا ۲۰ ثانیه. status یکی از queued، in_progress، completed یا failed است و progress درصد پیشرفت را می‌گوید.

  3. گرفتن فایل

    وقتی completed شد، GET /videos/{id}/content فایل MP4 را می‌دهد.

ساختن کار#

POSThttps://gisoo.pro/api/v1/videos
cURL POST /videos
curl https://gisoo.pro/api/v1/videos \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "Slow aerial shot over a misty tea plantation in northern Iran at dawn, soft light",
    "seconds": "8",
    "size": "1280x720"
  }'
JSON پاسخ: کار ساخته شد
{
  "id": "vid_7c2e9b4f1a0d3e8c6b5a2f1e",
  "object": "video",
  "created_at": 1790000000,
  "completed_at": null,
  "expires_at": null,
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "seconds": "8",
  "size": "1280x720",
  "usd": "1.120000",
  "refunded": false,
  "error": null
}
model string الزامی
مدل ویدیو؛ از GET /models?type=video.
prompt string الزامی
توصیف صحنه، حداکثر ۴٬۰۰۰ نویسه: موضوع، حرکت دوربین، نور، حال‌وهوا، صدا.
seconds string
مدت ویدیو: ۴، ۸، ۱۲ ثانیه (مقدار مجاز هر مدل در capabilities.seconds). پیش‌فرض ۴.
size string
ابعاد: افقی مثل 1280x720 یا عمودی مثل 720x1280. مقدارهای مجاز هر مدل در capabilities.sizes؛ اگر نفرستید یا auto بفرستید، اولین اندازهٔ مجاز همان مدل.

پرسیدن وضعیت و گرفتن فایل#

# 1) ask for the status every 10-20 seconds
curl https://gisoo.pro/api/v1/videos/vid_7c2e9b4f1a0d3e8c6b5a2f1e -H "Authorization: Bearer $GISOO_API_KEY"

# 2) when status is "completed", download the MP4
curl -L https://gisoo.pro/api/v1/videos/vid_7c2e9b4f1a0d3e8c6b5a2f1e/content \
  -H "Authorization: Bearer $GISOO_API_KEY" --output tea.mp4

# thumbnail (webp) or sprite sheet (jpeg)
curl "https://gisoo.pro/api/v1/videos/vid_7c2e9b4f1a0d3e8c6b5a2f1e/content?variant=thumbnail" \
  -H "Authorization: Bearer $GISOO_API_KEY" --output thumb.webp
  • GET /videos/{id}/content به‌طور پیش‌فرض خود ویدیو را می‌دهد؛ ?variant=thumbnail تصویر کوچک (webp) و ?variant=spritesheet نوار فریم‌ها (jpeg). با ?download=1 فایل برای ذخیره فرستاده می‌شود.
  • فایل تا حدود ۴۸ ساعت بعد از ساخت در دسترس است (expires_at). همان روز دانلود و در فضای خودتان ذخیره کنید.
  • GET /videos?limit=20 ویدیوهای همین پروژه را، تازه‌ترین اول، فهرست می‌کند.
  • هر ویدیو فقط با کلیدهای همان پروژه‌ای دیده می‌شود که ساختش.

هزینه و برگشت هزینه#

قیمت ویدیو به‌ازای هر ثانیه است و طول توصیف روی آن اثر ندارد. قاب بزرگ‌تر از قاب پایه گران‌تر است؛ قاب ۱۰۲۴p حدود ۱.۶۷ برابر قیمت پایه.

modelهر ثانیه (قاب پایه)ویدیوی ۸ ثانیه‌ایاندازه‌ها
sora-2 $0.14 $1.12 1280x720, 720x1280
sora-2-pro $0.42 $3.36 1280x720, 720x1280, 1792x1024, 1024x1792
veo-3.1 $0.56 $4.48 1280x720, 720x1280, 1920x1080, 1080x1920, 3840x2160, 2160x3840
veo-3.1-fast $0.14 $1.12 1280x720, 720x1280, 1920x1080, 1080x1920, 3840x2160, 2160x3840
veo-3.1-lite $0.07 $0.56 1280x720, 720x1280, 1920x1080, 1080x1920
  • هزینه همان لحظه‌ای کم می‌شود که سازنده کار را می‌پذیرد، چون ساختن از همان لحظه شروع می‌شود. مبلغش در فیلد usd کار آمده است.
  • ویدیویی که ساخته نشود، هزینه‌اش خودکار برمی‌گردد؛ یک بار و کامل. status: "failed" و refunded: true را می‌بینید.
  • کاری که بیش از ۲۵ دقیقه تمام نشود ناموفق حساب می‌شود و هزینه‌اش برمی‌گردد، حتی اگر صفحه یا برنامهٔ شما دیگر وضعیتش را نپرسد.
  • DELETE /videos/{id} کاری را که هنوز تمام نشده لغو می‌کند و هزینه‌اش را برمی‌گرداند.
توصیف خوب برای ویدیو

مثل فیلم‌نامهٔ یک نما بنویسید: موضوع و محل («a tea plantation at dawn»)، حرکت دوربین («slow aerial dolly»)، نور و رنگ، و صدا («birdsong, no music»). یک صحنه در هر کلیپ بهتر از چند صحنهٔ پشت هم جواب می‌دهد. توصیف انگلیسی معمولاً دقیق‌تر دنبال می‌شود.

سیاست محتوایی

سازنده درخواست‌هایی را که با سیاستش جور نیست رد می‌کند؛ مثلاً چهرهٔ آدم‌های واقعی یا محتوای دارای حق نشر. درخواست ردشده هزینه ندارد.

پاسخ پرسشتان را پیدا نکردید؟

شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.

تیکت پشتیبانی