Skip to main content
FFmpeg API cho phép bạn chuyển mã, cắt xén, chuyển đổi và xử lý file video, âm thanh hoàn toàn trên server. Bạn cung cấp một URL nguồn và một lệnh FFmpeg; MADIAD Hub tải file về, chạy job và cung cấp kết quả để tải về. Không có chức năng tải lên file nhị phân, các file đầu vào phải truy cập được qua HTTPS. API trả về job_id ngay lập tức; quá trình xử lý là bất đồng bộ, bạn cần kiểm tra trạng thái định kỳ rồi tải về kết quả.
Không có webhook cho FFmpeg. Kiểm tra trạng thái định kỳ (polling) là cách DUY NHẤT để biết một job đã xong. Webhooks chỉ phát sự kiện cho việc đăng bài và cho thay đổi kết nối tài khoản, không có sự kiện nào cho job FFmpeg. Đừng thiết kế hệ thống của bạn dựa trên một callback FFmpeg.
Các job FFmpeg yêu cầu gói trả phí. Tài khoản chưa kích hoạt gói có 0 phút FFmpeg. Kích hoạt gói Starter trở lên để sử dụng tính năng này.

Quy trình hoạt động của một job

1

Gửi

POST đến /v1/ffmpeg/jobs với một hoặc nhiều URL nguồn và một lệnh FFmpeg. API xác thực lệnh, đặt trước quota và đưa job vào hàng đợi. Bạn nhận được job_id.
2

Kiểm tra

GET /v1/ffmpeg/jobs/:id cho đến khi statusfinished.
3

Tải về

GET /v1/ffmpeg/jobs/:id/result để nhận file đã xử lý dưới dạng stream.

Gửi một job

Body của request

Response

Kiểm tra trạng thái

Response

duration_secnull cho đến khi job hoàn thành; giá trị thực tế của thời lượng đầu ra sẽ được điền vào sau khi hoàn tất.

Tải về kết quả

Khi statusfinished, hãy stream file đầu ra:
Response là một binary stream với Content-Disposition: attachment. Bạn có thể lưu ra file hoặc giữ trong bộ nhớ.

Quy tắc lệnh

Trường full_command phải đáp ứng tất cả các quy tắc sau. Request vi phạm sẽ trả về 400 invalid_request trước khi tiêu tốn bất kỳ quota nào. Ký tự xuống dòng trong lệnh được tự động chuyển thành khoảng trắng, nên bạn có thể dán lệnh nhiều dòng trực tiếp.

Phần mở rộng đầu ra được phép

output_extension phải là một trong các giá trị sau (không có dấu chấm ở đầu): Bất kỳ giá trị nào khác sẽ trả về 400 invalid_request.

Quota và thanh toán

Mức sử dụng FFmpeg được tính bằng phút FFmpeg. Trong v1, mỗi job có chi phí cố định là 1 phút, bất kể thời lượng thực tế của đầu ra. Quota được đặt trước tại thời điểm gửi và được hoàn lại tự động nếu job không thể vào hàng đợi. Giới hạn hàng tháng theo gói. Hạn mức này tính cho cả tài khoản: không nhân theo số Profile, mọi thương hiệu của bạn dùng chung một quota. Khi hết quota hàng tháng, API trả về 429 quota_exceeded. Hạn mức được đặt lại vào đúng ngày trong tháng mà gói của bạn được kích hoạt (giờ Việt Nam, UTC+7), không phải ngày mùng 1. Mức sử dụng cho biết chính xác ngày bắt đầu và ngày gia hạn của chu kỳ hiện tại.

Xác thực và giới hạn tốc độ

Tất cả endpoint FFmpeg đều dùng chung cơ chế xác thực Bearer API key với phần còn lại của MADIAD Hub, xem Xác thực. Giới hạn tốc độ là 120 request/phút mỗi tài khoản trên tất cả endpoint FFmpeg. Vượt quá giới hạn này sẽ nhận 429 kèm header Retry-After cho biết thời gian cần chờ.

Quyền sở hữu job

Job chỉ thuộc về tài khoản đã tạo ra nó. Kiểm tra trạng thái hoặc tải về job của tài khoản khác sẽ trả về 404 not_found, không có quyền truy cập chéo tài khoản.

Lỗi

Ví dụ thực tế

1. Gửi: chuyển đổi MP4 sang WebM tối ưu cho web

2. Kiểm tra cho đến khi hoàn thành

3. Tải về kết quả