ورودی ویدئو — Video Inputs

• URLها: برای ویدئوهای عمومی در دسترس کارآمدترند، چون نیازی به کدگذاری محلی ندارند.
• Data URL با base64: برای فایل‌های محلی یا ویدئوهای خصوصی که دسترسی عمومی ندارند لازم است.

ورودی ویدئو — Video Inputs

می‌توانید فایل‌های ویدئو را از طریق endpoint /v1/chat/completions و با نوع محتوای video_url به مدل‌های سازگار بفرستید. فیلد url می‌تواند یک URL یا یک Data URL با کدگذاری base64 باشد. فقط مدل‌هایی با قابلیت پردازش ویدئو این درخواست‌ها را مدیریت می‌کنند.

برای یافتن مدل‌هایی که ورودی ویدئو را پشتیبانی می‌کنند، می‌توانید در صفحهٔ مدل‌ها بر اساس modal ورودی «video» فیلتر کنید.

استفاده از URL ویدئو

برای ویدئوهای عمومی، می‌توانید URL را مستقیم بفرستید. توجه کنید که برای Google Gemini روی AI Studio فقط لینک‌های YouTube پشتیبانی می‌شوند:

import os

import requests

url = "https://app.asha-ai.ir/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['ASHA_API_KEY']}",
    "Content-Type": "application/json",
}

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Please describe what's happening in this video.",
            },
            {
                "type": "video_url",
                "video_url": {
                    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
                },
            },
        ],
    }
]

payload = {
    "model": "~google/gemini-2.5-flash",
    "messages": messages,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch(
  "https://app.asha-ai.ir/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "~google/gemini-2.5-flash",
      messages: [
        {
          role: "user",
          content: [
            { type: "text", text: "Please describe what's happening in this video." },
            {
              type: "video_url",
              video_url: {
                url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
              },
            },
          ],
        },
      ],
    }),
  }
);

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

curl https://app.asha-ai.ir/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -d '{
    "model": "~google/gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Please describe what'''s happening in this video." },
          { "type": "video_url", "video_url": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } }
        ]
      }
    ]
  }'

استفاده از ویدئو با کدگذاری Base64

برای ویدئوهای ذخیره‌شده به‌صورت محلی، می‌توانید آن‌ها را به‌صورت Data URL با کدگذاری base64 بفرستید:

import base64
import os

import requests

def encode_video_to_base64(video_path):
    with open(video_path, "rb") as video_file:
        return base64.b64encode(video_file.read()).decode("utf-8")

url = "https://app.asha-ai.ir/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['ASHA_API_KEY']}",
    "Content-Type": "application/json",
}

# Read and encode the video
video_path = "path/to/your/video.mp4"
base64_video = encode_video_to_base64(video_path)
data_url = f"data:video/mp4;base64,{base64_video}"

messages = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's in this video?",
            },
            {
                "type": "video_url",
                "video_url": {
                    "url": data_url,
                },
            },
        ],
    }
]

payload = {
    "model": "~google/gemini-2.5-flash",
    "messages": messages,
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

import fs from "fs/promises";

async function encodeVideoToBase64(videoPath: string): Promise<string> {
  const videoBuffer = await fs.readFile(videoPath);
  const base64Video = videoBuffer.toString("base64");
  return `data:video/mp4;base64,${base64Video}`;
}

// Read and encode the video
const videoPath = "path/to/your/video.mp4";
const base64Video = await encodeVideoToBase64(videoPath);

const response = await fetch(
  "https://app.asha-ai.ir/v1/chat/completions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ASHA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "~google/gemini-2.5-flash",
      messages: [
        {
          role: "user",
          content: [
            { type: "text", text: "What's in this video?" },
            {
              type: "video_url",
              video_url: {
                url: base64Video,
              },
            },
          ],
        },
      ],
    }),
  }
);

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

# Base64-encode your video file
VIDEO_BASE64=$(base64 < video.mp4 | tr -d 'n')
DATA_URL="data:video/mp4;base64,$VIDEO_BASE64"

curl https://app.asha-ai.ir/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -d '{
    "model": "~google/gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What'''s in this video?" },
          { "type": "video_url", "video_url": { "url": "'"$DATA_URL"'" } }
        ]
      }
    ]
  }'

فرمت‌های پشتیبانی‌شده

آشا از این فرمت‌های ویدئو پشتیبانی می‌کند:

• video/mp4
• video/mpeg
• video/mov
• video/webm

کاربردهای رایج

ورودی ویدئو طیف گسترده‌ای از برنامه‌ها را ممکن می‌کند:

• خلاصه‌سازی ویدئو: تولید خلاصهٔ متنی از محتوای ویدئو.
• تشخیص اشیا و فعالیت: شناسایی اشیا، افراد و حرکات در ویدئو.
• درک صحنه: توصیف مکان، محیط و بافت.
• تحلیل ورزشی: تحلیل بازی، حرکات و تاکتیک‌ها.
• نظارت و امنیت: پایش و تحلیل تصاویر دوربین.
• محتوای آموزشی: تحلیل ویدئوهای آموزشی و ارائهٔ بینش.

بهترین روش‌ها

ویدئو می‌تواند روی اندازهٔ فایل و هزینهٔ پردازش تأثیر زیادی بگذارد. این نکات را در نظر بگیرید:

ملاحظات اندازهٔ فایل

• در صورت امکان ویدئو را فشرده کنید تا حجم بدون افت کیفیت قابل توجه کم شود.
• ویدئو را برش بزنید و فقط بخش‌های مرتبط را بفرستید.
• رزولوشن مناسب انتخاب کنید؛ رزولوشن پایین‌تر (مثل 720p به‌جای 4K) حجم را کم می‌کند و برای بیشتر کارهای تحلیل کافی است.
• نرخ فریم: برای ویدئوهایی که تفکیک زمانی بالا حیاتی نیست، نرخ فریم پایین‌تر حجم را کم می‌کند.

طول بهینهٔ ویدئو

• برای هر مدل، سقف طول ویدئو ممکن است متفاوت باشد؛ مستندات همان مدل را بررسی کنید.
• برای ویدئوهای طولانی، فرستادن چند بخش کوتاه‌تر را در نظر بگیرید.
• به‌جای کل محتوای طولانی، روی لحظه‌های کلیدی تمرکز کنید.

مبادلهٔ کیفیت و حجم

• کیفیت بالا (1080p و بالاتر، bitrate بالا): بهترین گزینه برای تحلیل دقیق بصری، تشخیص اشیا و خواندن متن.
• کیفیت متوسط (720p، bitrate متوسط): برای بیشتر کارهای تحلیل عمومی مناسب است.
• کیفیت پایین‌تر (480p، bitrate پایین): برای درک پایهٔ صحنه و تشخیص حرکت قابل قبول است.

پشتیبانی از URL ویدئو به تفکیک ارائه‌دهنده

پشتیبانی از URL ویدئو بین ارائه‌دهنده‌ها تفاوت زیادی دارد:

• Google Gemini (AI Studio): فقط لینک‌های YouTube را پشتیبانی می‌کند (مثل https://www.youtube.com/watch?v=...).
• Google Gemini (Vertex AI): URL ویدئو را پشتیبانی نمی‌کند؛ به‌جای آن از Data URL با base64 استفاده کنید.
• سایر ارائه‌دهندگان: برای پشتیبانی از URL ویدئو، مستندات همان مدل را بررسی کنید.

عیب‌یابی

ویدئو پردازش نمی‌شود؟

• بررسی کنید مدل ورودی ویدئو را پشتیبانی می‌کند (فیلد input_modalities شامل "video" باشد).
• اگر از URL ویدئو استفاده می‌کنید، مطمئن شوید ارائه‌دهنده URL ویدئو را پشتیبانی می‌کند.
• برای Gemini روی AI Studio، حتماً از لینک YouTube استفاده کنید، نه لینک مستقیم فایل.
• اگر URL ویدئو کار نکرد، به‌جای آن Data URL با base64 را امتحان کنید.
• بررسی کنید فرمت ویدئو پشتیبانی می‌شود.
• مطمئن شوید فایل ویدئو خراب نیست.

خطاهای فایل بزرگ؟

• ویدئو را فشرده کنید تا حجم کم شود.
• رزولوشن یا نرخ فریم را پایین بیاورید.
• ویدئو را به مدت کوتاه‌تری برش بزنید.
• سقف اندازهٔ فایلِ همان مدل را بررسی کنید.
• برای فایل‌های بزرگ، به‌جای base64 از URL ویدئو استفاده کنید (اگر ارائه‌دهنده پشتیبانی می‌کند).

نتایج تحلیل ضعیف؟

• مطمئن شوید کیفیت ویدئو برای کار مورد نظر کافی است.
• prompt واضح و مشخص دربارهٔ چیزی که باید تحلیل شود بنویسید.
• بررسی کنید طول ویدئو برای مدل مناسب است.
• مطمئن شوید محتوای ویدئو واضح و با نور کافی دیده می‌شود.

سؤالات متداول