POST
/api/ai/v1/videos
نیازمند کلید API
ساخت ویدیوی کوتاه از روی توصیف متنی، با مدلهای Sora. خروجی یک فایل MP4 همراه با صداست. فهرست مدلها و قیمت هر ثانیه در صفحهٔ مدلها.
این endpoint فایل برنمیگرداند، «کار» برمیگرداند
رندر یک ویدیو یک تا چند دقیقه طول میکشد و هیچ درخواست HTTP اینقدر باز نمیماند. پس POST /videos بلافاصله یک شناسهٔ کار (vid_…) میدهد؛ شما هر چند ثانیه وضعیتش را میپرسید و وقتی status برابر completed شد، فایل را میگیرید.
سه قدم کامل
import time
job = client.videos.create(
model="sora-2",
prompt="نمای هوایی از جادهٔ کوهستانی در مه صبحگاهی، دوربین آرام جلو میرود",
seconds="8",
size="1280x720",
)
while job.status in ("queued", "in_progress"):
time.sleep(5)
job = client.videos.retrieve(job.id)
if job.status == "completed":
content = client.videos.download_content(job.id)
content.write_to_file("clip.mp4")
import { writeFile } from "node:fs/promises";
let job = await client.videos.create({
model: "sora-2",
prompt: "نمای هوایی از جادهٔ کوهستانی در مه صبحگاهی، دوربین آرام جلو میرود",
seconds: "8",
size: "1280x720",
});
while (job.status === "queued" || job.status === "in_progress") {
await new Promise((r) => setTimeout(r, 5000));
job = await client.videos.retrieve(job.id);
}
if (job.status === "completed") {
const file = await client.videos.downloadContent(job.id);
await writeFile("clip.mp4", Buffer.from(await file.arrayBuffer()));
}
# ۱) ساخت کار
curl https://netarz.ir/api/ai/v1/videos \
-H "Authorization: Bearer $NETARZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "sora-2",
"prompt": "نمای هوایی از جادهٔ کوهستانی در مه صبحگاهی",
"seconds": "8",
"size": "1280x720"
}'
# ۲) پرسیدن وضعیت (هر چند ثانیه یکبار)
curl https://netarz.ir/api/ai/v1/videos/vid_xxx \
-H "Authorization: Bearer $NETARZ_API_KEY"
# ۳) گرفتن فایل، وقتی status برابر completed شد
curl https://netarz.ir/api/ai/v1/videos/vid_xxx/content \
-H "Authorization: Bearer $NETARZ_API_KEY" -o clip.mp4
{
"id": "vid_9f2c4a1b7e5d3c8a0b6f1e2d",
"object": "video",
"created_at": 1790108108,
"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 الزامی | sora-2 یا sora-2-pro. مدتها و ابعاد مجاز هر مدل در capabilities.seconds و capabilities.sizes آمده است. |
prompt الزامی | توصیف صحنه، تا ۴۰۰۰ کاراکتر. فارسی را مستقیم بفرستید. |
seconds | مدت ویدیو: 4، 8 یا 12. پیشفرض ۴ ثانیه. هزینه دقیقاً به همین نسبت بالا میرود. |
size | قاب تصویر: 1280x720 و 720x1280 روی هر دو مدل؛ 1792x1024 و 1024x1792 فقط روی sora-2-pro. اگر نفرستید یا auto بگذارید، اولین اندازهٔ همان مدل انتخاب میشود. |
وضعیت کار
| status | یعنی |
|---|---|
queued | پذیرفته شده و در نوبت رندر است. |
in_progress | در حال ساخت؛ progress درصد پیشرفت را میگوید. |
completed | آماده است؛ فایل را از /videos/{id}/content بگیرید. |
failed | ساخته نشد. علت در error میآید و هزینه به اعتبارتان برمیگردد. |
Endpointهای دیگر این خانواده
GET /videos— فهرست کارهای این پروژه، تازهترین اول. پارامترlimitتا ۱۰۰.GET /videos/{id}— وضعیت یک کار.GET /videos/{id}/content— خود فایل. با?variant=thumbnailتصویر بندانگشتی (WebP) و با?variant=spritesheetنوار فریمها (JPEG) را میگیرید.DELETE /videos/{id}— لغو یک رندر. اگر هنوز تحویل نشده باشد، هزینهاش برمیگردد.
قیمتگذاری
ویدیو بهازای هر ثانیهٔ ویدیوی ساختهشده حساب میشود، و نرخ هر ثانیه به ابعاد تصویر بستگی دارد. طول پرامپت در هزینه اثری ندارد.
- هزینه در همان لحظهای که ارائهدهنده کار را میپذیرد از اعتبارتان کم میشود؛ مبلغ دقیق در فیلد
usdهمان پاسخ اول آمده است. - اگر رندر با شکست تمام شود یا ارائهدهنده تحویلش ندهد، کل مبلغ خودکار به اعتبارتان برمیگردد و
refundedبرابرtrueمیشود. لازم نیست چیزی بخواهید. - قاب
1024pحدود ۱٫۶۷ برابر720pهزینه دارد. - نرخ دقیق هر مدل به تومان و دلار در صفحهٔ مدلها و کلید
per_secondدر فهرست قیمتها.
نکات
- فایل ساختهشده ۴۸ ساعت در دسترس است؛ همان اول دانلودش کنید و در فضای خودتان نگه دارید. بعد از آن
/contentخطایvideo_expiredمیدهد. - هر کار متعلق به همان پروژهای است که ساخته شده؛ کلید پروژهٔ دیگر آن را نمیبیند.
- کاری که بیش از ۲۵ دقیقه باز بماند، ناموفق حساب و هزینهاش برگردانده میشود.
- ویرایش ویدیوی موجود، ادامهدادن (extend) و remix روی درگاه ارائه نمیشود.