Video Inputs

Trạm AI hỗ trợ gửi file video đến các model tương thích thông qua API. Hướng dẫn này sẽ hướng dẫn cách làm việc với video qua API.

Với video, Trạm AI hỗ trợ cả URL trực tiếp lẫn data URL mã hóa base64:

• URL: phù hợp với video có thể truy cập công khai, vì không cần mã hóa cục bộ
• Data URL base64: bắt buộc đối với file cục bộ hoặc video riêng tư không thể truy cập công khai

Video Inputs

Request kèm file video gửi đến các model tương thích được hỗ trợ qua endpoint /v1/chat/completions với content type video_url. Trường url có thể là một URL hoặc một data URL mã hóa base64. Lưu ý rằng chỉ model có khả năng xử lý video mới xử lý được các request này.

Người dùng có thể tìm model hỗ trợ video bằng cách lọc theo modality video input trên trang Models.

Sử dụng video URL

Dưới đây là cách gửi một video bằng URL. Lưu ý rằng với Google Gemini trên AI Studio, chỉ link YouTube mới được hỗ trợ:

1
import OpenAI from 'openai';
2
3
const openai = new OpenAI({
4
  baseURL: 'https://api.staging.tram.ai.vn/v1',
5
  apiKey: '<TRAM_AI_API_KEY>',
6
});
7
8
const result = await openai.chat.completions.create({
9
  model: "google/gemini-2.5-flash",
10
  messages: [
11
    {
12
      role: "user",
13
      content: [
14
        {
15
          type: "text",
16
          text: "Please describe what's happening in this video.",
17
        },
18
        {
19
          type: "video_url",
20
          videoUrl: {
21
            url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
22
          },
23
        },
24
      ],
25
    },
26
  ],
27
  stream: false,
28
});
29
30
console.log(result);

Sử dụng video mã hóa base64

Với video lưu trữ cục bộ, người dùng có thể gửi chúng bằng cách mã hóa base64 dưới dạng data URL:

1
import OpenAI from 'openai';
2
import * as fs from 'fs';
3
4
const openai = new OpenAI({
5
  baseURL: 'https://api.staging.tram.ai.vn/v1',
6
  apiKey: '<TRAM_AI_API_KEY>',
7
});
8
9
async function encodeVideoToBase64(videoPath: string): Promise<string> {
10
  const videoBuffer = await fs.promises.readFile(videoPath);
11
  const base64Video = videoBuffer.toString('base64');
12
  return `data:video/mp4;base64,${base64Video}`;
13
}
14
15
// Read and encode the video
16
const videoPath = 'path/to/your/video.mp4';
17
const base64Video = await encodeVideoToBase64(videoPath);
18
19
const result = await openai.chat.completions.create({
20
  model: 'google/gemini-2.5-flash',
21
  messages: [
22
    {
23
      role: 'user',
24
      content: [
25
        {
26
          type: 'text',
27
          text: "What's in this video?",
28
        },
29
        {
30
          type: 'video_url',
31
          videoUrl: {
32
            url: base64Video,
33
          },
34
        },
35
      ],
36
    },
37
  ],
38
  stream: false,
39
});
40
41
console.log(result);

Các định dạng video hỗ trợ

Trạm AI hỗ trợ các định dạng video sau:

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

Các trường hợp sử dụng phổ biến

Video input mở ra nhiều ứng dụng đa dạng:

• Tóm tắt video: tạo bản tóm tắt dạng văn bản cho nội dung video
• Nhận dạng đối tượng và hoạt động: xác định đối tượng, con người và hành động trong video
• Hiểu bối cảnh: mô tả khung cảnh, môi trường và ngữ cảnh
• Phân tích thể thao: phân tích lối chơi, chuyển động và chiến thuật
• Giám sát: theo dõi và phân tích footage an ninh
• Nội dung giáo dục: phân tích video hướng dẫn và đưa ra nhận định

Hướng dẫn tối ưu

Cân nhắc về kích thước file

File video có thể rất lớn, ảnh hưởng đến cả thời gian tải lên lẫn chi phí xử lý:

• Nén video khi có thể để giảm kích thước file mà không mất nhiều chất lượng
• Cắt video để chỉ giữ lại các đoạn cần thiết
• Cân nhắc độ phân giải: độ phân giải thấp hơn (ví dụ 720p so với 4K) giúp giảm kích thước file mà vẫn dùng tốt cho hầu hết tác vụ phân tích
• Tốc độ khung hình: tốc độ khung hình thấp hơn có thể giảm kích thước file cho những video không yêu cầu độ phân giải thời gian cao

Độ dài video tối ưu

Mỗi model có thể có giới hạn khác nhau về thời lượng video:

• Kiểm tra tài liệu riêng của từng model để biết độ dài video tối đa
• Với video dài, hãy cân nhắc chia thành các đoạn ngắn hơn
• Tập trung vào những khoảnh khắc quan trọng thay vì gửi toàn bộ nội dung dài

Đánh đổi giữa chất lượng và kích thước

Cân bằng giữa chất lượng video và các yếu tố thực tế:

• Chất lượng cao (1080p+, bitrate cao): tốt nhất cho phân tích hình ảnh chi tiết, phát hiện đối tượng, nhận dạng văn bản
• Chất lượng trung bình (720p, bitrate vừa phải): phù hợp với hầu hết tác vụ phân tích thông thường
• Chất lượng thấp hơn (480p, bitrate thấp hơn): chấp nhận được cho việc hiểu bối cảnh cơ bản và nhận dạng hành động

Hỗ trợ video URL theo từng provider

Mức độ hỗ trợ video URL khác nhau đáng kể tùy theo provider:

• Google Gemini (AI Studio): chỉ hỗ trợ link YouTube (ví dụ https://www.youtube.com/watch?v=...)
• Google Gemini (Vertex AI): không hỗ trợ video URL — hãy dùng data URL mã hóa base64 thay thế
• Các provider khác: kiểm tra tài liệu riêng của từng model để biết mức độ hỗ trợ video URL

Khắc phục sự cố

Video không được xử lý?

• Xác minh model có hỗ trợ video input (kiểm tra capabilities của model qua Public Models API)
• Nếu dùng video URL, hãy xác nhận provider có hỗ trợ video URL (xem phần Hỗ trợ video URL theo từng provider ở trên)
• Với Gemini trên AI Studio, đảm bảo link YouTube chứ không phải URL trực tiếp của file video
• Nếu video URL không hoạt động, hãy thử dùng data URL mã hóa base64 thay thế
• Kiểm tra xem định dạng video có được hỗ trợ không
• Xác minh file video không bị hỏng

Lỗi file quá lớn?

• Nén video để giảm kích thước file
• Giảm độ phân giải hoặc tốc độ khung hình của video
• Cắt video xuống thời lượng ngắn hơn
• Kiểm tra giới hạn kích thước file riêng của từng model
• Cân nhắc dùng video URL (nếu provider hỗ trợ) thay vì mã hóa base64 cho các file lớn

Kết quả phân tích kém?

• Đảm bảo chất lượng video đủ tốt cho tác vụ
• Cung cấp prompt rõ ràng, cụ thể về nội dung cần phân tích
• Cân nhắc xem thời lượng video có phù hợp với model không
• Kiểm tra xem nội dung video có hiển thị rõ ràng và đủ ánh sáng không