API RapidVideoMaker

The REST API lets you process video files from any HTTP client — Python scripts, n8n workflows, third-party tools. Five modes available: Merge videos (multiple MP4), Edit audio (1 MP4 + 1 MP3), Create a video (1 JPG/PNG + 1 MP3), Overlay video (2 MP4 picture-in-picture). Processing is asynchronous: submit files, then poll for the result.

Nhận token API miễn phí

Tạo tài khoản để nhận token API — 20 yêu cầu mỗi ngày.

Tạo tài khoản miễn phí Đã có tài khoản? Đăng nhập

Quy trình làm việc hoàn chỉnh

Mỗi tích hợp đều theo cùng một chuỗi 4 bước:

Tạo công việc — POST /api/v1/render.php

Gửi tệp của bạn dưới dạng multipart/form-data với token Bearer. 1 ảnh JPG/PNG + 1 MP3 + mode=image_to_video → tạo video. 1 MP4 + 1 MP3 → chỉnh sửa âm thanh. Nhiều MP4 → ghép nối. Server trả về job_id duy nhất.

Chờ công việc — GET /api/v1/jobs.php?job_id=…

Polling endpoint này thường xuyên (mỗi 5–10 giây). Công việc trải qua queued → processing → ready (hoặc error).

Lấy URL tải xuống

Khi trạng thái là ready, phản hồi chứa trường download_url sẵn sàng sử dụng.

Tải xuống tệp — GET /api/download.php?job_id=…

Tải xuống MP4 cuối cùng. Tệp có sẵn trong 2 giờ sau khi công việc hoàn thành, sau đó tự động xóa.

Xác thực

Mỗi yêu cầu phải bao gồm token API của bạn. Hai định dạng được chấp nhận:

# Xác thực — Mỗi yêu cầu phải bao gồm token API của bạn. Hai định dạng được chấp nhận:
Authorization: Bearer rvm_your_token_here

# Alternative
X-API-Key: rvm_your_token_here

Token của bạn có trong khu vực thành viên — một token mỗi tài khoản, được tạo tự động khi đăng ký.

Hạn ngạch

Mỗi tài khoản thành viên có 20 yêu cầu mỗi ngày, chia sẻ giữa giao diện web và API. Các công việc thất bại không tiêu thụ hạn ngạch. Bộ đếm đặt lại lúc nửa đêm UTC.

Phản hồi POST bao gồm quota_used và quota_remaining. Khi vượt giới hạn, server phản hồi 429.

Giao diện + API = cùng một bộ đếm. Video được tạo từ giao diện web và yêu cầu API mỗi cái tiêu thụ 1 tín dụng từ cùng hạn ngạch hàng ngày.

Hàng đợi

Một công việc được xử lý mỗi lần. Nếu nhiều công việc được gửi đồng thời, chúng sẽ được xếp hàng và xử lý theo thứ tự đến. Trong khi chờ, phản hồi trạng thái bao gồm:

queue_position — vị trí công việc trong hàng đợi (1 = tiếp theo)
queue_total — tổng số công việc đang chờ
eta_minutes — thời gian ước tính trước khi xử lý bắt đầu

Áp dụng giới hạn tốc độ: endpoint /api/v1/jobs.php chấp nhận tối đa 12 cuộc gọi mỗi phút mỗi token. Khuyến nghị: 10 giây giữa mỗi cuộc gọi.

Chuyển cảnh có sẵn

Truyền transition_type=none (mặc định) để ghép trực tiếp, hoặc một trong các loại dưới đây để mờ dần giữa các clip:

none fade fadeblack dissolve wipeleft wiperight slideleft slideright zoomin circleclose

Thời lượng (transition_duration) từ 0.2 đến 2.0 giây.

Điểm cuối

Five modes, accessible via the mode field (omit mode with multiple MP4s to auto-detect fusion):

Sử dụng	Chế độ API	Tệp bắt buộc	Mô tả
Ghép video	`fusion`	2–20 tệp MP4	Các đoạn clip được lắp ráp liên tiếp theo thứ tự được cung cấp. Chuyển cảnh tùy chọn giữa các clip.
Chỉnh sửa âm thanh	`add_audio` hoặc `mix_audio`	1 MP4 + 1 MP3	Thay thế hoặc làm phong phú thêm track âm thanh của video. Track video không bao giờ được mã hóa lại. `add_audio` — âm thanh gốc bị xóa và thay thế hoàn toàn bằng MP3. `mix_audio` — âm thanh gốc được giữ lại và MP3 được phủ lên.
Tạo video	`image_to_video`	1 JPG/PNG + 1 MP3	Tạo video từ ảnh tĩnh và tệp âm thanh. Lớp phủ văn bản, mờ dần, độ phân giải và fps có thể cấu hình qua trường `options`.
Overlay video	`overlay_video`	2 MP4	Chồng video thứ hai lên video chính. Vị trí, kích thước, độ mờ và âm thanh có thể cấu hình qua trường `options`.
Văn bản thành MP3	`text_to_mp3`	(chỉ văn bản)	Chuyển đổi văn bản thành giọng nói và trả về tệp MP3. Không cần tải tệp lên — gửi `mode=text_to_mp3`, `text` và `lang` dưới dạng trường biểu mẫu. Hỗ trợ tất cả 20 ngôn ngữ của trang web.

Xác thực nghiêm ngặt: mỗi chế độ yêu cầu số lượng và loại tệp chính xác. add_audio và mix_audio chỉ chấp nhận 1 MP4 + 1 MP3. image_to_video chỉ chấp nhận 1 JPG/PNG + 1 MP3.

Quy tắc thời lượng: trong chế độ audio và image_to_video, thời lượng kết quả bị khóa theo thời lượng MP3.

Tham số chung (multipart/form-data)

Trường	Loại	Bắt buộc	Mô tả
videos[]	File[]	CÓ	Tệp cần xử lý. Tùy thuộc vào chế độ: 2–20 MP4, hoặc 1 MP4 + 1 MP3, hoặc 1 ảnh (JPG/PNG) + 1 MP3. Tối đa 500 MB mỗi tệp.
mode	string	*	`image_to_video` \| `add_audio` \| `mix_audio`. Bắt buộc cho ba chế độ này. Bị bỏ qua chỉ khi tất cả tệp là MP4 (`fusion`).
order	JSON		Chỉ chế độ `fusion` — mảng JSON chỉ mục xác định thứ tự clip.
transition_type	string		Chỉ chế độ `fusion`. Mặc định: `none`.
transition_duration	float		Chỉ chế độ `fusion`. Thời lượng 0.2–2.0 giây. Mặc định: `0.5`.
options	JSON		Chỉ chế độ `image_to_video` — đối tượng JSON các tham số render.
callback_url	string		URL công khai (http/https) được gọi khi công việc hoàn thành. Phản hồi bao gồm `webhook_secret`.

Tham số `options` — chế độ image_to_video

Tất cả đều tùy chọn. Giá trị không được cung cấp → mặc định được áp dụng bởi worker.

Khóa	Loại	Mặc định	Mô tả
text	string	""	Văn bản hiển thị dưới dạng lớp phủ. Trống = không có văn bản. Tối đa 500 ký tự.
font_size	int	60	Kích thước phông chữ tính bằng pixel. Phạm vi: 10–300.
text_color	string	"white"	Màu văn bản (ví dụ: `white`, `yellow`, `#ffffff`).
text_position	string	"center"	Vị trí văn bản: `center`, `top`, `bottom`.
box	bool	true	Nền bán trong suốt phía sau văn bản.
box_color	string	"black@0.4"	Màu + độ mờ ở định dạng FFmpeg: `color@opacity`.
fade_duration	float	0.5	Thời lượng mờ vào/ra tính bằng giây (0–2). 0 = không có hiệu ứng.
width	int	1080	Chiều rộng video tính bằng pixel (64–3840, buộc chẵn).
height	int	1920	Chiều cao video tính bằng pixel (64–3840, buộc chẵn).
fps	int	24	Tốc độ khung hình (1–60).
image_fit	string	"contain"	Chế độ đóng khung: `contain` = toàn bộ ảnh hiển thị; `cover` = phóng to để lấp đầy toàn bộ khung.
bg_color	string	"black"	Màu nền nếu ảnh không lấp đầy độ phân giải mục tiêu.
enable_image_motion	bool	false	Bật hoạt ảnh ảnh. Nếu `false`, ảnh giữ nguyên tĩnh.
image_motion_effect	string	"ken_burns"	Hiệu ứng hoạt ảnh. Giá trị chấp nhận: `zoom_in`, `zoom_out`, `pan_left_to_right`, `pan_right_to_left`, `ken_burns`, v.v.
motion_intensity	float	1.0	Cường độ hoạt ảnh ảnh (0.25–2.0). Nhân biên độ zoom và tốc độ pan.
text_effect	string	"none"	Hoạt ảnh lớp phủ văn bản. Giá trị chấp nhận: `none`, `fade_in`, `slide_up`, `slide_down`, `slide_left`, `bounce`.
text_effect_intensity	float	1.0	Cường độ hoạt ảnh văn bản (0.25–2.0). Bị bỏ qua nếu `text_effect` là `none`.
text_border_width	int	0	Độ dày viền đen xung quanh ký tự tính bằng pixel (0 = vô hiệu hóa).
text_mode	string	"static"	Chế độ hiển thị văn bản. `static` (mặc định): toàn bộ văn bản hiển thị từ frame đầu tiên. `word_by_word`: từ xuất hiện lần lượt theo tốc độ `word_reveal_speed`. Không dùng cùng `text_effect`: nếu `text_mode=word_by_word`, `text_effect` sẽ bị bỏ qua.
word_reveal_speed	float	1.5	Tốc độ hiển thị từng từ theo từ/giây (0.3–5.0, mặc định 1.5). Chỉ dùng với `text_mode=word_by_word`. Giá trị khuyên dùng để đồng bộ OpenAI TTS: 2.0.
word_anim	string	"none"	Hoạt ảnh xuất hiện của từng từ. `none` (mặc định): hiển thị ngay lập tức. `fade`: mỗi từ mới xuất hiện với fade 0.2s và crossfade. Chỉ dùng với `text_mode=word_by_word`.

Tham số `options` — chế độ overlay_video

Tất cả đều tùy chọn. Thứ tự tải lên quan trọng: tệp thứ nhất là video chính (nền), tệp thứ hai là video chồng (tiền cảnh). Dùng chroma_key để xóa nền xanh khỏi video chồng.

Khóa	Loại	Mặc định	Mô tả
position	string	"bottom-right"	Góc đặt video chồng: `top-left`, `top-right`, `bottom-left`, `bottom-right`, hoặc `center`.
scale	float	0.30	Kích thước video chồng theo tỷ lệ chiều rộng video chính. `0.25` = 25% chiều rộng. Phạm vi: 0.05–1.0.
opacity	float	1.0	Độ trong suốt của video chồng. `1.0` = hoàn toàn hiện, `0.0` = vô hình.
margin	int	10	Khoảng cách tính bằng pixel giữa video chồng và cạnh khung. Bị bỏ qua khi `position=center`. Phạm vi: 0–200.
audio	string	"main"	Âm thanh cần giữ lại. `main`: chỉ âm thanh video chính. `overlay`: chỉ âm thanh video chồng. `mix`: trộn cả hai.
chroma_key	bool	false	Đặt thành `true` để xóa nền xanh thuần (#00FF00) khỏi video chồng — hữu ích cho webcam hoặc hoạt hình quay trên phông xanh.
chroma_similarity	float	0.20	Độ dung sai chroma key. Thấp = khớp chặt. Cao = xóa rộng hơn. Khuyến nghị: `0.10–0.20` cho màu xanh kỹ thuật số, `0.25–0.45` cho màn hình vật lý. Phạm vi: 0.01–0.60.

Tham số `options` — Chỉnh sửa âm thanh (`mix_audio`)

Chỉ có sẵn với mode=mix_audio. Bị bỏ qua cho add_audio.

Khóa	Loại	Mặc định	Mô tả
mp3_volume	float	1.0	Âm lượng của MP3 được phủ (0.0 = im lặng, 1.0 = âm lượng gốc, 2.0 = gấp đôi).

Phản hồi thành công (HTTP 200)

{
  "success": true,
  "job_id": "a3f1c8d2e5b09471...",
  "mode": "fusion",              // "fusion" | "add_audio" | "mix_audio" | "image_to_video" | "overlay_video"
  "file_count": 2,
  "transition": null,
  "quota_used": 1,
  "quota_remaining": 9,
  "status_url": "https://rapidvideomaker.com/api/v1/jobs.php?job_id=a3f1c8..."
}

Ví dụ curl — chế độ image_to_video

curl -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@scene.jpg" \
  -F "videos[]=@narration.mp3" \
  -F "mode=image_to_video" \
  -F 'options={"text":"Chapter 1","font_size":72,"text_color":"white","text_position":"bottom","box":true,"box_color":"black@0.4","fade_duration":0.5,"width":1080,"height":1920,"image_fit":"contain","bg_color":"black","enable_image_motion":true,"image_motion_effect":"ken_burns","motion_intensity":1.0,"text_effect":"slide_up","text_effect_intensity":1.0}'
# image_fit           : "contain" | "cover"
# bg_color            : ignored if image_fit="cover"
# enable_image_motion : true = animation on, false (default) = static image
# image_motion_effect : zoom_in | zoom_out | pan_left_to_right | pan_right_to_left | pan_top_to_bottom | pan_bottom_to_top | zoom_pan_soft | ken_burns
# motion_intensity    : 0.25–2.0 — photo animation amplitude (default 1.0)
# text_effect         : none | fade_in | slide_up | slide_down | slide_left | bounce (ignored if text_mode=word_by_word)
# text_effect_intensity : 0.25–2.0 — text animation intensity (default 1.0)
# text_border_width   : 0–10 px — black outline around characters (0 = disabled)
# text_mode           : "static" (default) | "word_by_word" — reveal words one by one
# word_reveal_speed   : 0.3–5.0 w/s — speed for word_by_word mode (default 1.5, ~2.0 for OpenAI TTS)
# word_anim           : "none" (default) | "fade" — fade-in crossfade on each word (word_by_word only)

Ví dụ curl — Chỉnh sửa âm thanh

# Replace audio (deletes original)
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@my_video.mp4" \
  -F "videos[]=@my_music.mp3" \
  -F "mode=add_audio"

# Keep original audio + overlay MP3
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@my_video.mp4" \
  -F "videos[]=@my_music.mp3" \
  -F "mode=mix_audio" \
  -F 'options={"mp3_volume":0.7}'
# mp3_volume : 0.0 (muted) → 1.0 (original volume, default) → 2.0 (amplified)

Ví dụ curl — chế độ overlay_video

curl -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@main_video.mp4" \
  -F "videos[]=@overlay_video.mp4" \
  -F "mode=overlay_video" \
  -F 'options={"position":"bottom-right","scale":0.25,"opacity":1.0,"margin":20,"audio":"main"}'

# Green screen overlay
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@main_video.mp4" \
  -F "videos[]=@webcam_greenscreen.mp4" \
  -F "mode=overlay_video" \
  -F 'options={"position":"bottom-left","scale":0.35,"chroma_key":true,"chroma_similarity":0.15,"audio":"mix"}'
# position           : top-left | top-right | bottom-left | bottom-right | center (default: bottom-right)
# scale              : 0.05–1.0 — overlay width as fraction of main video (default 0.30)
# opacity            : 0.0–1.0 — overlay transparency (default 1.0)
# margin             : 0–200 px — gap from frame edge, ignored if center (default 10)
# audio              : main | overlay | mix — audio to keep (default: main)
# chroma_key         : true | false — remove green (#00FF00) background from overlay (default false)
# chroma_similarity  : 0.01–0.60 — green screen tolerance (default 0.20)

Ví dụ curl — Ghép video

curl -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@clip1.mp4" \
  -F "videos[]=@clip2.mp4" \
  -F "transition_type=fade" \
  -F "transition_duration=0.5"

Các trạng thái có thể

Trạng thái	Ý nghĩa	Trường bổ sung
queued	Trong hàng đợi, chưa được xử lý	`queue_position`, `queue_total`, `eta_minutes`
processing	Đang xử lý FFmpeg	—
ready	Hoàn thành — tệp có sẵn	`download_url`, `created_at`, `expires_at`
error	Xử lý thất bại	`error` (message)

Phản hồi theo trạng thái

queued

{
  "job_id": "a3f1c8...",
  "status": "queued",
  "queue_position": 2,
  "queue_total": 3,
  "eta_minutes": 7
}

ready

{
  "job_id": "a3f1c8...",
  "status": "ready",
  "download_url": "https://rapidvideomaker.com/api/download.php?job_id=a3f1c8...",
  "created_at": "2026-06-02T10:00:00+00:00",
  "expires_at": "2026-06-02T12:00:00+00:00"
}

Ví dụ curl

curl -H "Authorization: Bearer rvm_your_token" \
  "https://rapidvideomaker.com/api/v1/jobs.php?job_id=a3f1c8..."

Tham số chung (multipart/form-data)

apidocs_th_param	Loại	Mặc định	apidocs_th_desc
`page`	integer	1	Page number (starts at 1)
`limit`	integer	20	Results per page (max 50, default 20)

Phản hồi theo trạng thái

{
  "success": true,
  "jobs": [
    { "job_id": "a3f1c8...", "status": "ready", "mode": "fusion", "created_at": "2026-06-02T10:00:00+00:00", "expires_at": "2026-06-02T12:00:00+00:00", "download_url": "https://..." },
    ...
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}

Đăng một job đã hoàn thành (status=ready) lên một hoặc nhiều tài khoản mạng xã hội. Token phải thuộc về tài khoản thành viên (không phải token quản trị viên).

Điều kiện tiên quyết: Các tài khoản mạng xã hội (YouTube, TikTok) phải được kết nối qua OAuth trên trang Xuất bản trong khu vực thành viên trước khi sử dụng endpoint này. account_id của mỗi tài khoản được hiển thị ở đó.

Tham số chung (multipart/form-data)

apidocs_th_param	Loại	apidocs_th_required	apidocs_th_desc
`job_id`	string	apidocs_required	ID job (hex 32 ký tự) của video đã hoàn thành
`publications`	array	apidocs_required	Mảng các đối tượng đăng bài (tối đa 10)

Đối tượng đăng bài

apidocs_th_param	Loại	apidocs_th_required	apidocs_th_desc
`account_id`	integer	apidocs_required	ID tài khoản mạng xã hội đã kết nối — xem trên trang Xuất bản trong khu vực thành viên
`title`	string	—	Tiêu đề video (tối đa 512 ký tự)
`description`	string	—	Mô tả video (tối đa 5 000 ký tự)
`tags`	string	—	Thẻ phân cách bằng dấu phẩy (tối đa 1 024 ký tự)
`visibility`	string	—	`public` \| `private` \| `unlisted` — Mặc định: public
`tiktok_mode`	string	—	`draft` \| `direct` — Chỉ TikTok — mặc định: direct
`tiktok_privacy`	string	chế độ direct	Chỉ TikTok — bắt buộc ở chế độ direct
`allow_comment`	boolean	—	Chỉ TikTok — cho phép bình luận
`allow_duet`	boolean	—	Chỉ TikTok — cho phép duet
`allow_stitch`	boolean	—	Chỉ TikTok — cho phép stitch
`your_brand`	boolean	—	Chỉ TikTok — nội dung quảng cáo hữu cơ ("Thương hiệu của bạn").
`branded_content`	boolean	—	Chỉ TikTok — tiết lộ nội dung thương hiệu
`tiktok_cover_ms`	integer	—	Chỉ TikTok — dấu thời gian khung ảnh bìa theo ms (0–60 000, mặc định 1 000)

Phản hồi theo trạng thái

{
  "success": true,
  "results": [
    {
      "account_id": 12,
      "pub_id": 47,
      "status": "published",
      "provider": "youtube",
      "url": "https://youtu.be/abc123"
    }
  ]
}

Mã lỗi cho từng bài đăng

apidocs_th_code	Ý nghĩa
`job_not_ready`	Job chưa hoàn thành
`mode_not_supported`	Không thể đăng job text_to_mp3
`account_not_found`	Không tìm thấy tài khoản hoặc đã ngắt kết nối
`tiktok_privacy_required`	Cần mức quyền riêng tư ở chế độ direct
`publication_failed`	Nhà cung cấp trả về lỗi khi tải lên

Ví dụ cURL

curl -X POST https://rapidvideomaker.com/api/v1/publish.php \
  -H "Authorization: Bearer rvm_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "a3f1c8...",
    "publications": [
      {
        "account_id": 12,
        "title": "My video",
        "description": "Created with RapidVideoMaker",
        "visibility": "public"
      }
    ]
  }'

Trả về tệp MP4 cuối cùng dưới dạng stream (Content-Type: video/mp4). Không yêu cầu token. Chỉ có sẵn khi trạng thái là ready.

Tệp được giữ trong 2 giờ sau khi công việc hoàn thành, sau đó bị xóa. Tải xuống ngay khi trạng thái trở thành ready.

Tham số tùy chọn

Tham số	Mô tả
filename	Tên được đề xuất cho tệp đã tải xuống (ví dụ: `video-cua-toi.mp4`)

Ví dụ curl

curl -o "output.mp4" \
  "https://rapidvideomaker.com/api/download.php?job_id=a3f1c8...&filename=output.mp4"

Webhook

Webhook là lựa chọn thay thế cho polling: thay vì kiểm tra trạng thái mỗi X giây, bạn cung cấp URL và server tự động gọi bạn khi công việc hoàn thành.

Cách hoạt động

Truyền callback_url trong POST đến /api/v1/render.php
Phản hồi chứa webhook_secret — giữ lại để xác minh chữ ký
Khi công việc đạt ready hoặc error, server gửi JSON POST đã ký đến URL của bạn
Xác minh chữ ký với HMAC-SHA256(webhook_secret, raw_body)

Ràng buộc: callback_url phải là URL có thể truy cập công khai (http hoặc https). Địa chỉ IP riêng tư, loopback và dự phòng bị chặn ở phía server. Thời gian chờ: 10 giây.

Payload nhận được

Thành công (ready)

{
  "job_id": "a3f1c8...",
  "status": "ready",
  "download_url": "https://rapidvideomaker.com
  /api/download.php?job_id=a3f1c8...",
  "timestamp": "2026-04-04T12:00:00+00:00"
}

Thất bại (error)

{
  "job_id": "a3f1c8...",
  "status": "error",
  "error": "FFmpeg xfade failed:...",
  "timestamp": "2026-04-04T12:00:00+00:00"
}

Header được gửi bởi server

Tiêu đề	Giá trị
Content-Type	`application/json`
X-RVM-Signature	`sha256=<hmac_hex>` — chữ ký HMAC-SHA256 của body thô
X-RVM-Job-Id	`job_id` liên quan

Xác minh chữ ký

# Python
import hmac, hashlib

def verify_webhook(secret: str, body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# Flask/FastAPI endpoint:
sig    = request.headers.get("X-RVM-Signature", "")
if not verify_webhook(WEBHOOK_SECRET, request.data, sig):
    return "Invalid signature", 403
data = request.get_json()

Mã lỗi

HTTP	Mã JSON	Nguyên nhân
401	unauthorized	Token bị thiếu, không hợp lệ hoặc bị thu hồi
400	missing_files	Không có tệp nào được nhận
400	too_few_files	Ít hơn 2 tệp được gửi
400	too_many_files	Hơn 20 tệp được gửi
400	invalid_mime	Tệp không được hỗ trợ — chỉ chấp nhận MP4, MP3 và JPG/PNG
400	wrong_file_count	Số lượng tệp không khớp với chế độ đã chọn
400	wrong_file_types	Loại tệp không khớp với chế độ đã chọn
400	invalid_file_combination	Kết hợp tệp không có chế độ được chỉ định không khớp với bất kỳ chế độ nào được hỗ trợ
400	invalid_options	Trường `options` không phải là JSON hợp lệ
400	invalid_option	Một giá trị trong `options` không hợp lệ
400	file_too_large	Một tệp vượt quá 500 MB
400	invalid_order	Mảng `order` không phải là hoán vị hợp lệ
400	invalid_job_id	Định dạng job_id sai (phải là 32 ký tự hex)
404	job_not_found	Không tìm thấy công việc — `job_id` không xác định hoặc chưa từng tồn tại
410	job_expired	Công việc đã hết hạn — tồn tại nhưng cửa sổ phục hồi 2 giờ đã qua
429	quota_exceeded	Đạt 20 công việc thành công/ngày
429	rate_limited	Hơn 12 cuộc gọi/phút trên `/api/v1/jobs.php`
500	server_error	Lỗi máy chủ nội bộ

Ví dụ tích hợp

Ví dụ cho mỗi chế độ — cài đặt requests với pip install requests.

Cấu hình chung

import requests, time, sys, json

API_BASE  = "https://rapidvideomaker.com"
API_TOKEN = "rvm_your_token_here"
HEADERS   = {"Authorization": f"Bearer {API_TOKEN}"}

Chế độ image_to_video — ảnh + âm thanh → video

with open("scene.jpg", "rb") as fi, open("narration.mp3", "rb") as fa:
    resp = requests.post(
        f"{API_BASE}/api/v1/render.php",
        headers=HEADERS,
        files=[
            ("videos[]", ("scene.jpg", fi, "image/jpeg")),
            ("videos[]", ("narration.mp3", fa, "audio/mpeg")),
        ],
        data={
            "mode": "image_to_video",
            "options": json.dumps({
                "text":          "Chapter 1",
                "font_size":     72,
                "text_color":    "white",
                "text_position": "bottom",
                "box":           True,
                "box_color":     "black@0.4",
                "fade_duration": 0.5,
                "width":              1080,
                "height":             1920,
                "image_fit":          "contain",  # "contain" | "cover"
                "bg_color":           "black",    # ignored if image_fit="cover"
                "enable_image_motion": True,
                "image_motion_effect": "ken_burns",
                "motion_intensity":    1.0,        # 0.25–2.0 — photo animation amplitude
                "text_effect":         "slide_up", # none | fade_in | slide_up | slide_down | slide_left | bounce (ignored if text_mode=word_by_word)
                "text_effect_intensity": 1.0,      # 0.25–2.0 — text animation intensity
                # word-by-word reveal (mutually exclusive with text_effect):
                # "text_mode": "word_by_word", "word_reveal_speed": 2.0, "word_anim": "fade"
            }),
        },
    )

Chỉnh sửa âm thanh

# Replace audio (deletes original) — mode=add_audio
with open("video.mp4", "rb") as fv, open("music.mp3", "rb") as fa:
    resp = requests.post(
        f"{API_BASE}/api/v1/render.php",
        headers=HEADERS,
        files=[
            ("videos[]", ("video.mp4", fv, "video/mp4")),
            ("videos[]", ("music.mp3", fa, "audio/mpeg")),
        ],
        data={"mode": "add_audio"},
    )

# Keep original audio + overlay MP3 — mode=mix_audio
with open("video.mp4", "rb") as fv, open("music.mp3", "rb") as fa:
    resp = requests.post(
        f"{API_BASE}/api/v1/render.php",
        headers=HEADERS,
        files=[
            ("videos[]", ("video.mp4", fv, "video/mp4")),
            ("videos[]", ("music.mp3", fa, "audio/mpeg")),
        ],
        data={"mode": "mix_audio", "options": json.dumps({"mp3_volume": 0.7})},
        # mp3_volume : 0.0 = muted, 1.0 = original volume (default), 2.0 = amplified
    )

Chế độ overlay_video — hình trong hình

with open("main.mp4", "rb") as fm, open("overlay.mp4", "rb") as fo:
    resp = requests.post(
        f"{API_BASE}/api/v1/render.php",
        headers=HEADERS,
        files=[
            ("videos[]", ("main.mp4",    fm, "video/mp4")),
            ("videos[]", ("overlay.mp4", fo, "video/mp4")),
        ],
        data={
            "mode": "overlay_video",
            "options": json.dumps({
                "position": "bottom-right",  # top-left | top-right | bottom-left | bottom-right | center
                "scale":    0.25,             # 0.05–1.0 — overlay width fraction
                "opacity":  1.0,             # 0.0–1.0 — transparency
                "margin":   20,              # 0–200 px — gap from frame edge
                "audio":    "main",          # main | overlay | mix
                # green screen: "chroma_key": True, "chroma_similarity": 0.15
            }),
        },
    )

Ghép video

with open("clip1.mp4", "rb") as f1, open("clip2.mp4", "rb") as f2:
    resp = requests.post(
        f"{API_BASE}/api/v1/render.php",
        headers=HEADERS,
        files=[
            ("videos[]", ("clip1.mp4", f1, "video/mp4")),
            ("videos[]", ("clip2.mp4", f2, "video/mp4")),
        ],
        data={"transition_type": "fade", "transition_duration": "0.5"},
    )

Polling + tải xuống (chung cho tất cả các chế độ)

resp.raise_for_status()
job_id = resp.json()["job_id"]
print(f"Job created: {job_id}")

for _ in range(120):          # timeout 10 min (120 × 5s)
    r = requests.get(
        f"{API_BASE}/api/v1/jobs.php",
        headers=HEADERS,
        params={"job_id": job_id},
    )
    data   = r.json()
    status = data["status"]

    if status == "queued":
        pos = data.get("queue_position", "?")
        eta = data.get("eta_minutes", "?")
        print(f"Queued — position {pos}, ETA ~{eta} min")
    elif status == "processing":
        print("Processing…")
    elif status == "ready":
        download_url = data["download_url"]
        break
    elif status == "error":
        sys.exit(f"Error: {data.get('error')}")

    time.sleep(5)
else:
    sys.exit("Timeout: job not completed after 10 min")

r = requests.get(download_url, stream=True)
with open("output.mp4", "wb") as f:
    for chunk in r.iter_content(65536):
        f.write(chunk)
print("Downloaded: output.mp4")

Hai cách tiếp cận trong n8n: polling (vòng lặp trạng thái) hoặc webhook (server gọi n8n). Webhook được khuyến nghị.

Cách A — Webhook (được khuyến nghị)

Chỉ 3 node, không có vòng lặp.

Node 1 — Kích hoạt Webhook
Thêm node Webhook làm đầu vào quy trình làm việc (phương thức POST).

Node 2 — Tạo công việc (HTTP Request)

Phương thức	`POST`
URL	`https://rapidvideomaker.com/api/v1/render.php`
Xác thực	Header Auth — `Authorization: Bearer rvm_…`
Loại nội dung Body	`Form-Data Multipart`
Body params	Trường nhị phân `videos[]` cho mỗi clip + Trường văn bản `callback_url`

Giữ webhook_secret từ phản hồi trong biến quy trình làm việc để xác minh chữ ký.

Node 3 — Xử lý kết quả (trong quy trình làm việc được kích hoạt bởi webhook)
Khi n8n nhận POST của server, $json.status là ready hoặc error.

Để xác minh chữ ký: so sánh {{ $headers['x-rvm-signature'] }} với HMAC-SHA256 từ webhook_secret của bạn.

Cách B — Polling (không có webhook)

5 node, vòng lặp trạng thái mỗi 10 giây.

Node 1 — Tạo công việc — cùng cấu hình không có callback_url.

Node 2 — Chờ — 10 giây.

Node 3 — Poll trạng thái (HTTP Request GET)

URL	`https://rapidvideomaker.com/api/v1/jobs.php`
Query params	`job_id` = `{{ $('Node 1').item.json.job_id }}`
Xác thực	Header Auth — cùng token

Node 4 — If: {{ $json.status }} === 'ready' → true: Node 5 / false: quay lại Node 2.

Thêm bộ đếm lần lặp trong node Set để thoát vòng lặp sau 60 lần thử.

Node 5 — Tải xuống: HTTP Request GET trên {{ $json.download_url }}.

Bước 1 — Tạo công việc (chọn chế độ)

# fusion
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@clip1.mp4" -F "videos[]=@clip2.mp4")

# add_audio (replace audio)
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@video.mp4" -F "videos[]=@music.mp3" \
  -F "mode=add_audio")

# mix_audio (overlay music at 70% volume)
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@video.mp4" -F "videos[]=@music.mp3" \
  -F "mode=mix_audio" -F 'options={"mp3_volume":0.7}')

# image_to_video
JOB=$(curl -s -X POST https://rapidvideomaker.com/api/v1/render.php \
  -H "Authorization: Bearer rvm_your_token" \
  -F "videos[]=@scene.jpg" -F "videos[]=@narration.mp3" \
  -F "mode=image_to_video" \
  -F 'options={"text":"Chapter 1","font_size":72,"text_position":"bottom","fade_duration":0.5,"width":1080,"height":1920}')

JOB_ID=$(echo $JOB | grep -o '"job_id":"[^"]*"' | cut -d'"' -f4)
echo "Job ID: $JOB_ID"

Bước 2 — Polling

while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer rvm_your_token" \
    "https://rapidvideomaker.com/api/v1/jobs.php?job_id=$JOB_ID")
  STATE=$(echo $STATUS | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  echo "Status: $STATE"
  [ "$STATE" = "ready" ] && break
  [ "$STATE" = "error" ] && { echo "Error"; exit 1; }
  sleep 10
done

Bước 3 — Tải xuống

DOWNLOAD_URL=$(echo $STATUS | grep -o '"download_url":"[^"]*"' | cut -d'"' -f4)
curl -o output.mp4 "$DOWNLOAD_URL"

Thực hành tốt nhất

Tần suất polling: endpoint /api/v1/jobs.php giới hạn 12 cuộc gọi/phút mỗi token. Chờ ít nhất 5 giây giữa các cuộc gọi.
Thời gian chờ: triển khai thời gian chờ phía client (ví dụ: 10 phút).
Tải xuống nhanh: tải xuống tệp ngay khi trạng thái là ready. Bị xóa 2 giờ sau khi công việc hoàn thành.
Quản lý hạn ngạch: kiểm tra quota_remaining trong phản hồi POST.
Lỗi mạng: khi gặp lỗi mạng trong quá trình polling, hãy chờ và thử lại.

Tệp kết quả được giữ 2 giờ sau khi công việc hoàn thành, sau đó tự động xóa.

API RapidVideoMaker

Quy trình làm việc hoàn chỉnh

Xác thực

Hạn ngạch

Hàng đợi

Chuyển cảnh có sẵn

Điểm cuối

Tham số chung (multipart/form-data)

Tham số options — chế độ image_to_video

Tham số options — chế độ overlay_video

Tham số options — Chỉnh sửa âm thanh (mix_audio)

Phản hồi thành công (HTTP 200)

Ví dụ curl — chế độ image_to_video

Ví dụ curl — Chỉnh sửa âm thanh

Ví dụ curl — chế độ overlay_video

Ví dụ curl — Ghép video

Các trạng thái có thể

Phản hồi theo trạng thái

Ví dụ curl

Tham số chung (multipart/form-data)

Phản hồi theo trạng thái

Tham số chung (multipart/form-data)

Đối tượng đăng bài

Phản hồi theo trạng thái

Mã lỗi cho từng bài đăng

Ví dụ cURL

Tham số tùy chọn

Ví dụ curl

Webhook

Cách hoạt động

Payload nhận được

Header được gửi bởi server

Xác minh chữ ký

Mã lỗi

Ví dụ tích hợp

Cấu hình chung

Chế độ image_to_video — ảnh + âm thanh → video

Chỉnh sửa âm thanh

Chế độ overlay_video — hình trong hình

Ghép video

Polling + tải xuống (chung cho tất cả các chế độ)

Cách A — Webhook (được khuyến nghị)

Cách B — Polling (không có webhook)

Bước 1 — Tạo công việc (chọn chế độ)

Bước 2 — Polling

Bước 3 — Tải xuống

Thực hành tốt nhất

Tham số `options` — chế độ image_to_video

Tham số `options` — chế độ overlay_video

Tham số `options` — Chỉnh sửa âm thanh (`mix_audio`)