با POST /videos از روی توصیف متنی یک کلیپ کوتاه با صدا میسازید. ساختن ویدیو یک تا چند دقیقه طول میکشد، پس این endpoint بر خلاف بقیه فایل را همان لحظه برنمیگرداند:
یک «کار» (Job) با شناسهٔ vid_… میسازد، شما وضعیتش را میپرسید و وقتی آماده شد فایل را میگیرید.
سه مرحله#
- ساختن کار
POST /videosبا مدل، توصیف، مدت و اندازه. پاسخ شیء کار است باstatus: "queued". - پرسیدن وضعیت
GET /videos/{id}هر ۱۰ تا ۲۰ ثانیه.statusیکی ازqueued،in_progress،completedیاfailedاست وprogressدرصد پیشرفت را میگوید. - گرفتن فایل
وقتی
completedشد،GET /videos/{id}/contentفایل MP4 را میدهد.
ساختن کار#
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"
}'
{
"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
}
GET /models?type=video.capabilities.seconds). پیشفرض ۴.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
import os, time, requests
BASE = "https://gisoo.pro/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['GISOO_API_KEY']}"}
job = requests.post(f"{BASE}/videos", headers=HEADERS, json={
"model": "sora-2",
"prompt": "Slow aerial shot over a misty tea plantation in northern Iran at dawn, soft light",
"seconds": "8",
"size": "1280x720",
}, 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("progress"))
if job["status"] == "completed":
with requests.get(f"{BASE}/videos/{job['id']}/content", headers=HEADERS, stream=True, timeout=300) as r:
r.raise_for_status()
with open("tea.mp4", "wb") as f:
for chunk in r.iter_content(1 << 16):
f.write(chunk)
else:
print("failed:", job["error"], "refunded:", job["refunded"])
const BASE = "https://gisoo.pro/api/v1";
const headers = { Authorization: "Bearer " + process.env.GISOO_API_KEY, "Content-Type": "application/json" };
let job = await (await fetch(BASE + "/videos", {
method: "POST",
headers,
body: JSON.stringify({ model: "sora-2", prompt: "A paper boat drifting on a rainy street, cinematic", seconds: "4" }),
})).json();
while (job.status === "queued" || job.status === "in_progress") {
await new Promise((r) => setTimeout(r, 15000));
job = await (await fetch(BASE + "/videos/" + job.id, { headers })).json();
}
if (job.status === "completed") {
const file = await fetch(BASE + "/videos/" + job.id + "/content", { headers });
await import("node:fs").then((fs) => fs.promises.writeFile("boat.mp4", Buffer.from(await file.arrayBuffer())));
}
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) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.