ن نِت اَرز · مستندات API هوش مصنوعی
همهٔ مستندات
مدل‌ها و قیمت‌ها مرجع تعاملی دریافت کلید

تولید ویدیو

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

base_url: https://netarz.ir/api/ai/v1 به‌روزرسانی: 1405/07/01
POST /api/ai/v1/videos نیازمند کلید API

ساخت ویدیوی کوتاه از روی توصیف متنی، با مدل‌های Sora. خروجی یک فایل MP4 همراه با صداست. فهرست مدل‌ها و قیمت هر ثانیه در صفحهٔ مدل‌ها.

این endpoint فایل برنمی‌گرداند، «کار» برمی‌گرداند

رندر یک ویدیو یک تا چند دقیقه طول می‌کشد و هیچ درخواست HTTP این‌قدر باز نمی‌ماند. پس POST /videos بلافاصله یک شناسهٔ کار (vid_…) می‌دهد؛ شما هر چند ثانیه وضعیتش را می‌پرسید و وقتی status برابر completed شد، فایل را می‌گیرید.

سه قدم کامل

Python
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")
Node.js
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
# ۱) ساخت کار
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 روی درگاه ارائه نمی‌شود.