پرش به محتوا

API ساخت ویدیو

API ساخت ویدیو با وئو (Veo) و سورا (Sora): ساختن کار، پرسیدن وضعیت و گرفتن MP4، ویدیو از روی عکس با Veo، مدت و ابعاد مجاز و برگشت هزینهٔ رندر ناموفق.

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

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

API ساخت ویدیو گیسو هم سورا (Sora) را دارد و هم وئو (Veo) را، با یک مسیر و یک کلید؛ مدل‌های دیگری مثل Kling، Seedance و Wan هم از همین مسیر می‌آیند. نمونه‌کدهای ابتدای صفحه مدل sora-2 را صدا می‌زنند و بخش وئو می‌گوید Veo چه فرقی دارد و چطور از روی یک عکس ویدیو بسازید.

سه مرحله

  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

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

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 بفرستید، اولین اندازهٔ مجاز همان مدل.

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

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

# 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 ویدیوهای همین پروژه را، تازه‌ترین اول، فهرست می‌کند.
  • هر ویدیو فقط با کلیدهای همان پروژه‌ای دیده می‌شود که ساختش.

API وئو (Veo)

veo-3.1، veo-3.1-fast و veo-3.1-lite همان روال سه‌مرحله‌ای بالا را دارند. فرق‌هایشان با Sora:

  • مدت: ۴، ۶ یا ۸ ثانیه؛ در قاب 1080p و 4K فقط ۸ ثانیه.
  • قاب: افقی یا عمودی، از 1280x720 تا 3840x2160 بسته به مدل (capabilities.sizes). Veo همیشه صدای صحنه را هم با تصویر می‌سازد.
  • از روی عکس: عکس را در فیلد image (base64 یا data URL) بفرستید تا فریم اول ویدیو شود؛ برای عکس محصول، فیگور یا منظره. Veo عکسی را که چهرهٔ آدم واقعی دارد اغلب نمی‌پذیرد.
  • آنچه نباید باشد: در negative_prompt بنویسید چه چیزی در کلیپ نیاید، مثلاً «text, watermark».

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

Python وئو: ویدیو از روی عکس
import base64, os, time, requests

BASE = "https://gisoo.pro/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['GISOO_API_KEY']}"}

photo = base64.b64encode(open("product.jpg", "rb").read()).decode()

job = requests.post(f"{BASE}/videos", headers=HEADERS, json={
    "model": "veo-3.1-fast",
    "prompt": "The camera slowly circles the product on the table, soft morning light, gentle ambient sound",
    "image": "data:image/jpeg;base64," + photo,   # first frame
    "negative_prompt": "text, watermark",
    "seconds": "6",
    "size": "720x1280",                            # vertical, for stories and reels
}, timeout=60).json()

while job["status"] in ("queued", "in_progress"):
    time.sleep(15)
    job = requests.get(f"{BASE}/videos/{job['id']}", headers=HEADERS, timeout=30).json()

print(job["status"], job.get("usd"), job.get("refunded"))

نسخه‌های وئو را با هزینهٔ هر ثانیه در صفحهٔ خانوادهٔ وئو و دو خانواده را کنار هم در مقایسهٔ Veo و Sora ببینید. بدون کد هم، ساخت ویدیو با هوش مصنوعی در اپ گیسو با همین مدل‌ها کار می‌کند.

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

قیمت ویدیو به‌ازای هر ثانیه است و طول توصیف روی آن اثر ندارد. قاب بزرگ‌تر از قاب پایه گران‌تر است؛ قاب ۱۰۲۴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
openrouter/alibaba/happyhorse-1.0 $0.1511 $1.2091 1280x720, 720x1280, 720x720, 960x720, 720x960, 1680x720, 720x1680, 1920x1080, 1080x1920, 1080x1080, 1440x1080, 1080x1440, 2520x1080, 1080x2520
openrouter/alibaba/happyhorse-1.1 $0.1511 $1.2091 1280x720, 720x1280, 720x720, 960x720, 720x960, 1680x720, 720x1680, 1920x1080, 1080x1920, 1080x1080, 1440x1080, 1080x1440, 2520x1080, 1080x2520
openrouter/alibaba/wan-2.6 $0.1529 $1.2238 1280x720, 1080x1920, 720x1280, 1920x1080
openrouter/alibaba/wan-2.7 $0.1529 $1.2238 1280x720, 720x1280, 1920x1080, 1080x1920, 720x720, 1080x1080, 960x720, 720x960, 1440x1080, 1080x1440
openrouter/alibaba/wan-3.0 $0.0764 $0.6119 854x480, 480x480, 480x854, 1280x720, 720x720, 720x1280, 1920x1080, 1080x1080, 1080x1920
openrouter/alibaba/wan-3.0-prime $0.104 $0.8321 854x480, 480x480, 480x854, 1280x720, 720x720, 720x1280, 1920x1080, 1080x1080, 1080x1920
openrouter/black-forest-labs/flux-3-video $0.26 $2.0804 1280x720, 720x720, 720x1280, 1920x1080, 1080x1080, 1080x1920, 2560x1440, 1440x1440, 1440x2560, 3840x2160, 2160x2160, 2160x3840
openrouter/bytedance/seedance-1-5-pro $0.0198 $0.1586 480x480, 480x640, 480x854, 480x1120, 640x480, 720x720, 720x960, 720x1280, 720x1680, 854x480, 960x720, 1080x1080, 1080x1440, 1080x1920, 1080x2520, 1120x480, 1280x720, 1440x1080, 1680x720, 1920x1080, 2520x1080
openrouter/bytedance/seedance-2.0 $0.0578 $0.4626 480x480, 480x640, 480x854, 640x480, 854x480, 1120x480, 720x720, 720x960, 720x1280, 720x1680, 960x720, 1280x720, 1680x720, 1080x1080, 1080x1440, 1080x1920, 1440x1080, 1920x1080, 2520x1080, 3840x2160, 2160x3840, 2160x2160, 2880x2160, 2160x2880, 5040x2160
openrouter/bytedance/seedance-2.0-fast $0.0346 $0.2775 480x480, 480x640, 480x854, 640x480, 854x480, 1120x480, 720x720, 720x960, 720x1280, 720x1680, 960x720, 1280x720, 1680x720
openrouter/bytedance/seedance-2.0-mini $0.0289 $0.2313 480x480, 480x640, 480x854, 640x480, 854x480, 1120x480, 720x720, 720x960, 720x1280, 720x1680, 960x720, 1280x720, 1680x720
openrouter/bytedance/seedance-2.5 $0.1571 $1.257 854x480, 752x560, 640x640, 560x752, 480x854, 992x432, 1280x720, 1112x834, 960x960, 834x1112, 720x1280, 1470x630
openrouter/google/veo-3.1 $0.6119 $4.8952 1280x720, 1080x1920, 1920x1080, 720x1280, 3840x2160, 2160x3840
openrouter/google/veo-3.1-fast $0.1529 $1.2238 1280x720, 1080x1920, 1920x1080, 720x1280, 3840x2160, 2160x3840
openrouter/google/veo-3.1-lite $0.0764 $0.6119 1280x720, 720x1280, 1920x1080, 1080x1920
openrouter/heygen/heygen-video-1 $0.0305 $0.2447 854x480, 480x480, 480x854, 1366x768, 768x768, 768x1366, 2560x1440, 1440x1440, 1440x2560
openrouter/kwaivgi/kling-video-o1 $0.1713 $1.3706 1280x720, 720x1280, 720x720
openrouter/kwaivgi/kling-v3.0-pro $0.2569 $2.0559 1280x720, 720x1280, 720x720
openrouter/kwaivgi/kling-v3.0-std $0.1927 $1.5419 1280x720, 720x1280, 720x720
openrouter/minimax/hailuo-3 $0.1988 $1.5909 2560x1440, 1440x1440, 1440x2560
openrouter/minimax/hailuo-3-max $0.0764 $0.6119 1366x768, 768x768, 768x1366, 854x480, 480x480, 480x854
openrouter/minimax/hailuo-2.3 $0.1249 $0.9998 1920x1080
openrouter/runway/gen-4.5 $0.1835 $1.4685 1280x720, 720x1280
openrouter/x-ai/grok-imagine-video $0.0764 $0.6119 854x480, 1280x720, 480x854, 720x1280, 480x480, 720x720, 640x480, 960x720, 480x640, 720x960, 720x480, 1080x720, 480x720, 720x1080
openrouter/x-ai/grok-imagine-video-1.5 $0.1223 $0.979 854x480, 480x854, 480x480, 1280x720, 720x1280, 720x720, 1920x1080, 1080x1920, 1080x1080
openrouter/x-ai/grok-imagine-video-1.5-lite $0.0305 $0.2447 854x480, 480x854, 480x480, 1280x720, 720x1280, 720x720, 1920x1080, 1080x1920, 1080x1080
  • هزینه همان لحظه‌ای کم می‌شود که سازنده کار را می‌پذیرد، چون ساختن از همان لحظه شروع می‌شود. مبلغش در فیلد usd کار آمده است.
  • ویدیویی که ساخته نشود، هزینه‌اش خودکار برمی‌گردد؛ یک بار و کامل. status: "failed" و refunded: true را می‌بینید.
  • کاری که بیش از ۲۵ دقیقه تمام نشود ناموفق حساب می‌شود و هزینه‌اش برمی‌گردد، حتی اگر صفحه یا برنامهٔ شما دیگر وضعیتش را نپرسد.
  • DELETE /videos/{id} کاری را که هنوز تمام نشده لغو می‌کند و هزینه‌اش را برمی‌گرداند.
توصیف خوب برای ویدیو

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

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

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

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

API وئو (Veo) و سورا (Sora) هر دو در گیسو هست؟

بله، هر دو از یک مسیر، POST /videos، و با یک کلید: veo-3.1، veo-3.1-fast و veo-3.1-lite از Google و sora-2 و sora-2-pro از OpenAI. فهرست زنده را GET /models?type=video می‌دهد.

از روی عکس هم ویدیو می‌سازد؟

با Veo بله: عکس را در فیلد image (base64 یا data URL) بفرستید تا فریم اول ویدیو شود. Veo عکسی را که چهرهٔ آدم واقعی دارد اغلب نمی‌پذیرد و درخواست ردشده هزینه ندارد.

ویدیو چند ثانیه می‌تواند باشد؟

Veo کلیپ ۴، ۶ یا ۸ ثانیه‌ای می‌سازد (در قاب 1080p و 4K فقط ۸ ثانیه) و Sora کلیپ ۴، ۸ یا ۱۲ ثانیه‌ای. مقدار مجاز هر مدل در capabilities.seconds آن آمده است.

اگر ویدیو ساخته نشود، هزینه‌اش برمی‌گردد؟

بله، خودکار و کامل؛ در پاسخ status: "failed" و refunded: true را می‌بینید. کاری را هم که هنوز تمام نشده با DELETE /videos/{id} لغو می‌کنید و هزینه‌اش برمی‌گردد.

قدم بعدی

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

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

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