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ả.

FFmpeg không có webhook, phải tự hỏi trạng thái

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.
Xử lý video được bật theo yêu cầu, không đi kèm gói nào. Mặc định không gói nào có sẵn tính năng này; tài khoản chưa được bật sẽ nhận 403 forbidden ở mọi endpoint FFmpeg. Gửi thư tới info@madiad.com kèm mô tả việc bạn định xử lý, chúng tôi sẽ bật cho tài khoản của bạn.

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.

Điều kiện sử dụng và hạn mức

Xử lý video được cấp theo từng tài khoản, không gộp vào gói. Mọi gói đều có hạn mức bằng không; chúng tôi đặt hạn mức cho bạn khi bạn yêu cầu. Trước đó, POST /v1/ffmpeg/jobs trả về 403 forbidden. Đây là câu trả lời về quyền sử dụng, không phải về hạn mức đã dùng hết, nên thử lại sẽ không thay đổi được gì. Sau khi được bật, hạn mức tính bằng lượt: gửi một job tốn một lượt, bất kể video dài bao nhiêu. Hạn mức được đặt trước tại thời điểm gửi và hoàn lại tự động nếu job không vào được hàng đợi. Hạn mức tính cho cả tài khoản: không nhân theo số Profile, mọi thương hiệu dùng chung một hạn mức. Hạn mức đặt lại vào đúng ngày trong tháng mà gói đượ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 con số chính xác của bạn, tính năng đã được bật hay chưa, và ngày bắt đầu / gia hạn của chu kỳ hiện tại. Dùng hết hạn mức đã được cấp thì API trả về 429 quota_exceeded.

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ả