Submit a video generation request

یک درخواست تولید ویدیو را ثبت می‌کند.

نقطهٔ پایانی POST /videos یک کار تولید ویدیو را ارسال می‌کند. آشا کار را به‌صورت داخلی دنبال می‌کند و پاسخ نهایی را — با ویدیوهای آماده در unsigned_urls — برمی‌گرداند؛ در نتیجه نیازی به نظرسنجی یا وبکوب برای دریافت نتیجه نیست.

Endpoint

                POST
                /videos
              

https://app.asha-ai.ir/v1/videos

احراز هویت

با کلید API آشا از طریق هدر Authorization: Bearer <ASHA_API_KEY> احراز هویت کنید.

بدنهٔ درخواست

فیلد	نوع	توضیح
`model`	string	الزامی. شناسه یا slug مدل تولید ویدیو (مثل `video-model-canonical-slug`).
`prompt`	string	توضیح متنی ویدیوی موردنظر؛ برای مدل‌های تصویر‑به‑ویدیو که فقط به قاب اولیه نیاز دارند الزامی نیست.
`duration`	integer	مدت‌زمان ویدیو به ثانیه؛ حداقل `1`.
`aspect_ratio`	string	نسبت ابعاد: `16:9`، `9:16`، `1:1`، `4:3`، `3:4`، `3:2`، `2:3`، `21:9` یا `9:21`.
`resolution`	string	وضوح خروجی: `480p`، `720p`، `768p`، `1080p`، `1K`، `2K` یا `4K`.
`size`	string	اندازهٔ خروجی به‌صورت `WIDTHxHEIGHT` (مثل `1280x720`).
`generate_audio`	boolean	تولید همزمان صدا؛ مقدار پیش‌فرض به نقطهٔ پایانی/مدل بستگی دارد.
`seed`	number	دانهٔ تصادفی برای بازتولیدپذیر کردن خروجی.
`frame_images`	array	قاب‌های کنترل خروجی؛ هر مورد `{"frame_type": "first_frame"\|"last_frame", "image_url": "https://…"}`.
`input_references`	array	مراجع ورودی؛ هر مورد `{"input_type": "image"\|"audio"\|"video", "url": "https://…"}`. مراجع صوتی/ویدیویی فقط توسط پروایدرهای سازگار پشتیبانی می‌شوند.
`provider.options`	object	گزینه‌های گذر (passthrough) ویژهٔ پروایدر، کلیدزده با شناسهٔ پروایدر؛ تنها پارامترهای اجازه‌داده‌شده توسط مدل پذیرفته می‌شوند.

مثال درخواست

curl https://app.asha-ai.ir/v1/videos 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "video-model-canonical-slug",
    "prompt": "A cat walking on a beach at sunset",
    "duration": 5,
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

import requests

response = requests.post(
    'https://app.asha-ai.ir/v1/videos',
    headers={
        'Authorization': 'Bearer <ASHA_API_KEY>',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'video-model-canonical-slug',
        'prompt': 'A cat walking on a beach at sunset',
        'duration': 5,
        'aspect_ratio': '16:9',
        'generate_audio': True,
    },
)

data = response.json()
print(data['status'], len(data['unsigned_urls']))

const response = await fetch(
  'https://app.asha-ai.ir/v1/videos',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <ASHA_API_KEY>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'video-model-canonical-slug',
      prompt: 'A cat walking on a beach at sunset',
      duration: 5,
      aspect_ratio: '16:9',
      generate_audio: true,
    }),
  }
);

const data = await response.json();
console.log(data.status, data.unsigned_urls);

پاسخ موفق

پس از اتمام تولید، پاسخ نهایی با کد 200 برمی‌گردد:

                JSON
                200 OK
              

{
  "id": "req_9f8d1c2a",
  "status": "completed",
  "unsigned_urls": [
    "https://…signed-video-download-url…"
  ],
  "usage": {
    "cost": "0.50"
  }
}

فیلدهای پاسخ

فیلد	توضیح
`id`	شناسهٔ یکتای درخواست.
`status`	وضعیت نهایی کار؛ در پاسخ موفق `completed` است.
`unsigned_urls`	آرایهٔ آدرس (signed) ویدیوهای آمادهٔ دانلود.
`usage.cost`	هزینهٔ نهایی به‌صورت رشته (مثل `"0.50"`).

صبر تا اتمام تولید

آشا به‌جای برگرداندن فوری یک وضعیت میانه، کار تولید را به‌صورت داخلی رصد می‌کند و فقط پس از اتمام (وضعیت completed) پاسخ را برمی‌گرداند. اگر کار با شکست به پایان برسد، یک خطای HTTP مناسب برگردانده می‌شود.

خطاها

کد	توضیح
`400`	پارامترهای درخواست نامعتبر است یا ورودی بدشکل است.
`401`	هدر احراز هویت وجود ندارد یا اعتبارنامه نامعتبر است.
`402`	اعتبار کافی نیست؛ برای تکمیل درخواست باید موجودی افزوده شود.
`500`	خطای داخلی سرور.
`502`	ارائه‌دهنده خطای بالادستی برگرداند.