ویدیو و لیپ‌سینک

ساخت ویدیو

یک کار تولید ویدیو از روی توصیف و در صورت نیاز تصویر مرجع می‌سازد. پاسخ ۲۰۲ با شناسه‌ی کار است؛ وضعیت را پیگیری و فایل را بعداً دریافت می‌کنید.

POST/v1/videos

تولید ویدیو چند دقیقه طول می‌کشد، پس همیشه به صورت کار پس‌زمینه اجرا می‌شود. درخواست بلافاصله با 202 و شیئی با status: queued و شناسه‌ی job_... جواب می‌گیرد. بعد GET /v1/videos/{id} را با فاصله صدا بزنید تا status به completed، failed یا cancelled برسد، و فایل را با /content بردارید.

بدنه می‌تواند JSON یا multipart/form-data باشد. تصویر مرجع را یا به صورت فایل در فیلد input_reference بفرستید (حداکثر ۲۵ مگابایت)، یا در JSON به شکل URL، data URL با base64، یا { "image_url": "..." }. URL با محافظ SSRF دریافت می‌شود (حداکثر ۵۰ مگابایت) و فقط وقتی که حساب شما اعتبار دارد و درخواست محدودیتی نخورده است. نوع فایل از روی بایت‌ها تشخیص داده می‌شود و باید تصویر باشد.

مدت و نسبت تصویر

مدت و نسبت تصویر مجاز به مدل بستگی دارد. اگر نفرستید، اولین مقدار مجاز همان مدل به کار می‌رود. اگر مدل مدتی یا نسبتی را نپذیرد، خطای media_input_unsupported می‌گیرید و گزینه‌های مجاز آن مدل در error.details.options است. چون هزینه بر اساس همین مقادیر است، مقدار نامجاز بی‌صدا تغییر نمی‌کند.

اندازه

یا size (مثل 1280x720) بفرستید، یا aspect_ratio و resolution؛ هر دو با هم خطاست. size به نسبت و کیفیت تبدیل می‌شود: نسبت باید یکی از ۱۶:۹، ۹:۱۶ و ۱:۱ باشد، و اگر ضلع کوتاه‌تر بیشتر از ۹۰۰ پیکسل باشد 1080p در نظر گرفته می‌شود، وگرنه 720p.

اعتبار

اعتبار پیش از اجرا رزرو می‌شود. اگر کار شکست بخورد یا لغو شود، اعتبار رزروشده برمی‌گردد. اگر کار تمام شود، هزینه بر اساس مدت و کیفیت کسر می‌شود. این کارها و فایل‌هایشان در استودیو و گالری حساب شما دیده نمی‌شوند.

نمونه‌ها

curl https://1ai.ir/v1/videos \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "kling/kling-v3.0-pro",
  "prompt": "A red apple slowly rotating on a white table",
  "seconds": 5,
  "size": "1280x720"
}'
202پاسخ
{
  "id": "job_4Ws8nTqL3xYbCe7RmKh2Zf",
  "object": "video",
  "model": "kling/kling-v3.0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1793923200,
  "completed_at": null,
  "prompt": "A red apple slowly rotating on a white table",
  "seconds": "5",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "estimated_credits": 12,
  "credits": 0,
  "output": null,
  "error": null
}

بدنه‌ی درخواست

  • modelstringالزامی

    شناسه‌ی مدل ویدیو، برای نمونه kling/kling-v3.0-pro.

  • promptstringالزامی

    توصیف صحنه، بین ۱ و ۴٬۰۰۰ نویسه.

  • negative_promptstring

    چیزهایی که نباید در ویدیو بیایند، حداکثر ۲٬۰۰۰ نویسه. اثرش به مدل بستگی دارد.

  • secondsinteger | string

    مدت ویدیو به ثانیه. در multipart ناگزیر رشته است. مقدار مجاز را مدل تعیین می‌کند؛ پیش‌فرض اولین مدت مجاز همان مدل است.

  • sizestring

    اندازه به شکل عرضxارتفاع مثل 1280x720. همراه aspect_ratio یا resolution پذیرفته نمی‌شود.

  • aspect_ratiostring

    نسبت تصویر. گزینه‌های مدل ممکن است از این فهرست کمتر باشد؛ پیش‌فرض اولین نسبت مجاز مدل است.

    مقادیر مجاز:16:99:161:1
  • resolutionstring

    کیفیت تصویر. هر مدل ممکن است فقط بعضی را بپذیرد.

    مقادیر مجاز:720p1080p
  • input_referencefile

    تصویر مرجع: فایل در multipart، یا در JSON یک URL، data URL یا شیء { "image_url": "..." }. حداکثر ۲۵ مگابایت برای فایل و ۵۰ برای URL.

خطاها

  • invalid_request400

    فیلدی نامعتبر یا ناشناخته است، size همراه aspect_ratio یا resolution آمده، یا size نسبت ۱۶:۹، ۹:۱۶ یا ۱:۱ ندارد.

  • media_input_unsupported400

    مدل این مدت یا نسبت تصویر را نمی‌سازد. گزینه‌های مجاز در error.details.options است.

  • model_kind_mismatch400

    مدل داده‌شده مدل ویدیو نیست.

  • input_fetch_failed400

    فایل input_reference از روی URL دریافت نشد.

  • insufficient_credits402

    اعتبار برای رزرو هزینه کافی نیست.

  • model_not_found404

    مدل وجود ندارد یا کلید شما به آن دسترسی ندارد.

  • file_too_large413

    فایل آپلودشده از ۲۵ مگابایت بزرگ‌تر است.

  • no_routable_target400

    مدل فعلاً مسیر قابل استفاده ندارد.

صفحه‌های مرتبط