تولید ویدیو

کاکوتی از طریق API اختصاصی، تولید ویدیو از متن (و در صورت نیاز تصویر مرجع) را پشتیبانی می‌کند. برخلاف درخواست‌های متنی یا تصویری که بلافاصله پاسخ می‌دهند، تولید ویدیو ناهمگام است؛ یعنی ابتدا یک کار (Job) ثبت می‌شود و پس از اتمام، نتیجه را دریافت می‌کنید.

🔧 پیش‌نیازها

1. داشتن کلید API از پنل کاکوتی
2. نصب بودن curl یا ابزار مشابه برای ارسال درخواست HTTP
3. اعتبار کافی در حساب برای پوشش هزینه‌ی تولید ویدیو

🧭 آدرس‌های API

برای ثبت درخواست و پیگیری وضعیت، کلید API را در هدر Authorization ارسال کنید:

Authorization: Bearer YOUR_API_KEY

🔍 یافتن مدل‌های ویدیویی

برای مشاهده‌ی مدل‌های در دسترس و پارامترهای پشتیبانی‌شده‌ی هر مدل، از endpoint مدل‌های ویدیو استفاده کنید:

curl --request GET \
  --url https://llm-api.kakoti.com/api/v1/videos/models \
  --header 'Content-Type: application/json'

پاسخ شامل آرایه‌ی data است که برای هر مدل اطلاعاتی مانند موارد زیر را برمی‌گرداند:

{
  "data": [
    {
      "id": "kwaivgi/kling-v3.0-std",
      "canonical_slug": "kwaivgi/kling-v3.0-std",
      "name": "Kling v3.0 Standard",
      "description": "...",
      "supported_resolutions": ["720p", "1080p"],
      "supported_aspect_ratios": ["16:9", "9:16", "1:1"],
      "supported_sizes": ["1280x720", "1920x1080"],
      "pricing_skus": {
        "per-video-second": "0.50"
      },
      "allowed_passthrough_parameters": []
    }
  ]
}

💡 نکته

قبل از ارسال درخواست، با این endpoint بررسی کنید مدل انتخابی چه رزولوشن، نسبت تصویر و پارامترهایی را پشتیبانی می‌کند. همچنین می‌توانید از لیست مدل‌ها در پنل کاکوتی مدل مناسب را انتخاب کنید.

⚙️ نحوه کار

جریان کلی تولید ویدیو به این شکل است:

1. ثبت درخواست با POST /api/v1/videos/
2. دریافت شناسه‌ی کار (id) و آدرس پیگیری (polling_url)
3. بررسی دوره‌ای وضعیت با GET /api/v1/videos/{jobId} تا رسیدن به وضعیت completed
4. دانلود ویدیو از آدرس موجود در unsigned_urls یا endpoint محتوا

📝 ارسال درخواست تولید ویدیو

متن به ویدیو (Text-to-Video)

curl --request POST \
  --url https://llm-api.kakoti.com/api/v1/videos/ \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kwaivgi/kling-v3.0-std",
    "prompt": "پسری در حال بالا رفتن از کوه در فضایی فانتزی",
    "duration": 5
  }'

تصویر به ویدیو (Image-to-Video)

با فیلد frame_images می‌توانید فریم اول یا آخر را مشخص کنید:

curl --request POST \
  --url https://llm-api.kakoti.com/api/v1/videos/ \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kwaivgi/kling-v3.0-std",
    "prompt": "پسر شروع به بالا رفتن از کوه در فضایی فانتزی کند",
    "duration": 3,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": {
          "url": "https://download.kakoti.com/images/first.png"
        },
        "frame_type": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://download.kakoti.com/images/last.png"
        },
        "frame_type": "last_frame"
      }
    ]
  }'

مثال Python

import requests
import time

url = "https://llm-api.kakoti.com/api/v1/videos/"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "kwaivgi/kling-v3.0-std",
    "prompt": "پسری در حال بالا رفتن از کوه در فضایی فانتزی",
    "duration": 5,
}

# مرحله ۱: ثبت درخواست
response = requests.post(url, headers=headers, json=payload)
result = response.json()

job_id = result["id"]
polling_url = result["polling_url"]
print(f"کار ثبت شد: {job_id}")
print(f"وضعیت: {result['status']}")

# مرحله ۲: پیگیری تا اتمام
while True:
    time.sleep(30)
    status = requests.get(polling_url, headers=headers).json()
    print(f"وضعیت: {status['status']}")

    if status["status"] == "completed":
        content_url = status["unsigned_urls"][0]
        video = requests.get(content_url)
        with open("output.mp4", "wb") as f:
            f.write(video.content)
        print("ویدیو ذخیره شد: output.mp4")
        break
    elif status["status"] == "failed":
        print(f"خطا: {status.get('error', 'نامشخص')}")
        break

📋 پارامترهای درخواست

رزولوشن‌های رایج

• 480p، 720p، 1080p
• 1K، 2K، 4K

نسبت‌های تصویر رایج

• 16:9 — افقی (وایداسکرین)
• 9:16 — عمودی
• 1:1 — مربع
• 4:3، 3:4 — استاندارد
• 3:2، 2:3 — عکاسی
• 21:9، 9:21 — فوق‌عریض / فوق‌بلند

🖼️ استفاده از تصویر

دو روش برای ارسال تصویر وجود دارد:

• frame_images — فریم اول یا آخر را مشخص می‌کند (image-to-video). هر آیتم باید frame_type برابر first_frame یا last_frame داشته باشد.
• input_references — تصاویر مرجع برای راهنمایی سبک و محتوا (reference-to-video). مدل از آن‌ها به‌عنوان الهام بصری استفاده می‌کند، نه فریم دقیق.

اگر هر دو فیلد ارسال شود، frame_images اولویت دارد و درخواست به‌صورت image-to-video پردازش می‌شود.

image-to-video با frame_images

{
  "model": "kwaivgi/kling-v3.0-std",
  "prompt": "شخصی در حال عبور از جنگل",
  "frame_images": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first-frame.png"
      },
      "frame_type": "first_frame"
    }
  ],
  "resolution": "1080p"
}

reference-to-video با input_references

{
  "model": "kwaivgi/kling-v3.0-std",
  "prompt": "شعله‌ی خورشیدی عظیم در کنار یک سیاره",
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/style-ref.png"
      }
    }
  ],
  "resolution": "1080p"
}

تنظیمات اختصاصی ارائه‌دهنده

با فیلد provider می‌توانید پارامترهای خاص هر ارائه‌دهنده را ارسال کنید. فقط گزینه‌های مربوط به ارائه‌دهنده‌ی تطبیق‌یافته ارسال می‌شوند:

{
  "model": "kwaivgi/kling-v3.0-std",
  "prompt": "تایم‌لپس از شکفتن یک گل",
  "provider": {
    "options": {
      "provider-slug": {
        "parameters": {
          "negativePrompt": "تار، کیفیت پایین"
        }
      }
    }
  }
}

پارامترهای مجاز هر مدل در فیلد allowed_passthrough_parameters پاسخ endpoint مدل‌ها مشخص شده است.

📤 فرمت پاسخ

پاسخ ثبت درخواست

بلافاصله پس از ثبت، جزئیات کار را دریافت می‌کنید:

{
  "id": "dbJypFPsmiXzx7VpQt47",
  "polling_url": "https://llm-api.kakoti.com/api/v1/videos/dbJypFPsmiXzx7VpQt47",
  "status": "pending"
}

پیگیری وضعیت

برای بررسی وضعیت کار:

curl --request GET \
  --url https://llm-api.kakoti.com/api/v1/videos/dbJypFPsmiXzx7VpQt47 \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json'

پاسخ پس از اتمام معمولاً شبیه نمونه‌ی زیر است:

{
  "id": "dbJypFPsmiXzx7VpQt47",
  "generation_id": "gen-1234567890-abcdef",
  "polling_url": "https://llm-api.kakoti.com/api/v1/videos/dbJypFPsmiXzx7VpQt47",
  "status": "completed",
  "unsigned_urls": [
    "https://llm-api.kakoti.com/api/v1/videos/dbJypFPsmiXzx7VpQt47/content?index=0"
  ],
  "usage": {
    "cost": 0.25
  }
}

وضعیت‌های کار

دانلود ویدیو

پس از completed، آرایه‌ی unsigned_urls آدرس دانلود را دارد. همچنین می‌توانید مستقیماً از endpoint محتوا استفاده کنید:

curl "https://llm-api.kakoti.com/api/v1/videos/dbJypFPsmiXzx7VpQt47/content?index=0" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output video.mp4

پارامتر index به‌صورت پیش‌فرض 0 است و در صورت تولید چند خروجی ویدیویی کاربرد دارد.

💡 توصیه‌ها

• پرامپت دقیق: جزئیات حرکت، زاویه‌ی دوربین، نور و ترکیب‌بندی صحنه را در توضیح بنویسید.
• رزولوشن مناسب: رزولوشن بالاتر زمان و هزینه‌ی بیشتری دارد؛ متناسب با نیاز انتخاب کنید.
• فاصله‌ی پیگیری: هر ۳۰ ثانیه یک‌بار وضعیت را بررسی کنید. تولید ویدیو معمولاً بین ۳۰ ثانیه تا چند دقیقه طول می‌کشد.
• مدیریت خطا: همیشه وضعیت failed و فیلد error را بررسی کنید.
• تصاویر مرجع: تصاویر باکیفیت و مرتبط با خروجی مورد نظر ارسال کنید.

🔧 عیب‌یابی

کار مدت زیادی در pending مانده؟

• تولید ویدیو بسته به مدل، رزولوشن و بار سرور ممکن است چند دقیقه طول بکشد.
• پیگیری دوره‌ای را ادامه دهید.

تولید ناموفق بود؟

• فیلد error در پاسخ پیگیری را بخوانید.
• مطمئن شوید مدل انتخابی از تولید ویدیو پشتیبانی می‌کند.
• پرامپت را با قوانین مدل هماهنگ کنید.
• در صورت استفاده از تصویر، آدرس‌ها باید در دسترس و با فرمت پشتیبانی‌شده باشند.

مدل پیدا نشد؟

• از endpoint GET /api/v1/videos/models لیست مدل‌ها را بگیرید.
• شناسه‌ی مدل را دقیق وارد کنید (مثلاً kwaivgi/kling-v3.0-std).

📚 مستندات مرتبط

• ارسال درخواست با curl — راهنمای درخواست‌های چت و متنی (OpenAI-compatible)
• استفاده از OpenAI SDK در Python — اتصال با کتابخانه رسمی OpenAI
• خدمات هوش مصنوعی — فهرست همه راهنماها