API RapidVideoMaker
REST API 可從任何 HTTP 客戶端處理影片檔案——Python 腳本、n8n 工作流程、第三方工具。五種模式：合併影片（多個 MP4/MOV）、編輯音訊（1 MP4/MOV + 1 MP3）、建立影片（1 JPG/PNG + 1 MP3）、影片疊加（2 MP4/MOV 畫中畫）。處理為非同步：提交檔案後輪詢結果。
完整工作流程
每個整合都遵循相同的4步驟序列：
1
建立任務 —
POST /api/v1/render.php使用Bearer令牌將文件作為
multipart/form-data發送。1張JPG/PNG圖像 + 1個MP3 + mode=image_to_video → 視訊生成。1個MP4/MOV + 1個MP3 → 音訊編輯。多個MP4/MOV → 合併。伺服器返回唯一的job_id。或 1 張圖片 + options.text + options.voice：語音由文字產生，不需 MP3。2
等待任務 —
GET /api/v1/jobs.php?job_id=…定期（每5-10秒）輪詢此端點。任務會經歷
queued → processing → ready（或error）。3
取得下載URL
當狀態變為
ready時，回應包含可用的download_url欄位。4
下載檔案 —
GET /api/download.php?job_id=…下載最終MP4/MOV。檔案在任務完成後2小時內可用，之後自動刪除。
認證
每個請求必須包含您的API令牌。接受兩種格式：
# 認證 — 每個請求必須包含您的API令牌。接受兩種格式：
Authorization: Bearer rvm_your_token_here
# Alternative
X-API-Key: rvm_your_token_here
您的令牌可在會員區取得 — 每個帳號一個令牌，註冊時自動建立。
配額
每個會員帳號有每天20個請求，在網頁介面和API之間共享。失敗的任務不消耗配額。計數器在UTC午夜重置。
POST回應包含quota_used和quota_remaining。超過限制時，伺服器回應429。
介面 + API = 相同計數器。從網頁介面建立的視訊和API請求各消耗同一日配額中的1個積分。
佇列
一次處理一個任務。如果同時提交多個任務，它們會排隊按順序處理。等待時，狀態回應包含：
queue_position— 任務在佇列中的位置（1 = 下一個處理）queue_total— 等待中的任務總數eta_minutes— 處理開始前的預估時間
適用速率限制：
/api/v1/jobs.php端點每個令牌最多接受每分鐘12次呼叫。建議：呼叫間隔10秒。 可用轉場效果
直接合併傳入transition_type=none（預設），或使用以下類型之一在片段間淡入淡出：
none
fade
fadeblack
dissolve
wipeleft
wiperight
slideleft
slideright
zoomin
circleclose
時長（transition_duration）在0.2到2.0秒之間。
端點
POST
/api/v1/render.php
建立視訊處理任務
五種模式，透過 mode 欄位指定（多個 MP4 省略 mode 自動偵測 fusion）：
| 用法 | API模式 | 所需檔案 | 描述 |
|---|---|---|---|
| 合併視訊 | fusion |
2-20個MP4/MOV檔案 | 片段按提供的順序首尾相連組裝。片段之間可選擇性加入轉場效果。 |
| 編輯音訊 | add_audio 或 mix_audio |
1個MP4/MOV + 1個MP3 | 取代或豐富視訊的音軌。視訊軌道永不重新編碼。add_audio — 原始音訊被刪除並完全替換為MP3。mix_audio — 原始音訊被保留，MP3被疊加。 |
| 建立視訊 | image_to_video |
1 張 JPG/PNG + 1 個 MP3 —— 或 1 張 JPG/PNG + 一段文字（options.text + options.voice）：產生語音 |
由一張靜態圖片和您的 MP3 —— 或僅由一段文字（options.text，語音由 options.voice 產生）—— 產生影片。文字疊加（固定、逐字或卡拉 OK）、淡入淡出、解析度和 fps 可透過 options 欄位設定。 |
| 影片疊加 | overlay_video |
2 MP4/MOV | 將第二個影片疊加在主影片上方。位置、大小、透明度和音訊可透過 options 欄位設定。 |
| 新增文字 | add_text |
1 個 MP4/MOV | 在現有影片上疊加文字（維持解析度、影格率與音訊）。文字設定與 image_to_video 相同，另可指定文字出現的時間。options.text 為必填。 |
| 文字轉MP3 | text_to_mp3 |
（僅文字） | 將文字轉換為語音並返回MP3檔案。無需上傳檔案 — 將 mode=text_to_mp3、text 和 lang 作為表單欄位傳送。支援網站的全部20種語言。 |
嚴格驗證：每種模式需要精確的檔案數量和類型。
add_audio和mix_audio只接受1個MP4/MOV + 1個MP3。image_to_video只接受1張JPG/PNG + 1個MP3。例外：使用 options.text + options.voice 時，image_to_video 只接受 1 張圖片——語音由文字產生（不需 MP3）。時長規則：在音訊和image_to_video模式下，結果時長鎖定為MP3時長。使用
options.voice 時，image_to_video 的長度等於由文字產生的語音長度（+0.6 秒）。公共參數（multipart/form-data）
| 欄位 | 類型 | 必填 | 描述 |
|---|---|---|---|
| videos[] | File[] | 是 | 要處理的檔案。根據模式不同：2-20個MP4/MOV，或1個MP4/MOV + 1個MP3，或1張圖像（JPG/PNG）+ 1個MP3。每個檔案最大500 MB。 |
| mode | string | * | image_to_video | add_audio | mix_audio | overlay_video | text_to_mp3。這些非fusion模式必填。僅上傳MP4/MOV檔案且省略mode時一律觸發fusion（串流複製拼接）——即使剛好上傳2個MP4/MOV，也絕不會觸發overlay_video。音訊編輯：add_audio刪除原始音訊，mix_audio保留原始音訊並疊加。若提供mode欄位，上傳的檔案必須完全相符——否則請求將被拒絕。 也接受 add_text：它是唯一只接收單一 MP4/MOV 檔案的模式，且需要 options.text。 |
| order | JSON | 僅限fusion模式 — 定義片段順序的索引JSON陣列。 | |
| transition_type | string | 僅限fusion模式。預設：none。 | |
| transition_duration | float | 僅限fusion模式。時長0.2-2.0秒。預設：0.5。 | |
| options | JSON | image_to_video, add_text, mix_audio 與 overlay_video 的算繪參數 JSON 物件（見下方表格）。 | |
| timings | File / string | image_to_video / add_text：卡拉OK時間軸檔案（SRT 或 LRC，最大 200 KB）——檔案欄位或純文字。顯示的文字取自檔案；強制 text_mode=karaoke；無法與 voice 同時使用。 | |
| callback_url | string | 任務完成時呼叫的公開URL（http/https）。回應包含webhook_secret。 |
options參數 — image_to_video模式
全部可選。未提供的值 → 由工作程序套用預設值。
| 鍵 | 類型 | 預設值 | 描述 |
|---|---|---|---|
| text | string | "" | 作為疊加顯示的文字。空 = 無文字。最多500個字元。 |
| font | string | "default" | 文字字型，依識別碼指定。可用值：default, dejavu-sans-bold, dejavu-serif, liberation-serif, dejavu-mono, amiri, noto-sans-sc (简体中文), noto-sans-tc (繁體中文), noto-sans-jp (日本語), noto-sans-kr (한국어), noto-sans-hebrew (עברית), noto-sans-thai (ไทย)。default = 標準字型（支援表情符號）；amiri = Naskh 字型，適合阿拉伯文文字。其他任何值都會回傳 invalid_option 錯誤。表情符號僅在 default 下顯示。 |
| font_size | int | 60 | 字型大小（像素）。範圍：10-300。 |
| text_color | string | "white" | 文字顏色（例如：white、yellow、#ffffff）。 |
| text_position | string | "center" | 文字位置：center、top、bottom。 |
| box | bool | true | 文字後面的半透明背景。 |
| box_color | string | "black@0.4" | FFmpeg格式的顏色 + 不透明度：color@opacity。 |
| fade_duration | float | 0.5 | 淡入/淡出時長（秒），0-2。0 = 無效果。 |
| width | int | 1080 | 視訊寬度（像素），64-3840，強制為偶數。 |
| height | int | 1920 | 視訊高度（像素），64-3840，強制為偶數。 |
| fps | int | 24 | 影格率（1-60）。 |
| image_fit | string | "contain" | contain: 完整顯示圖片或影片，並以所選背景填滿空白區域。 solid（預設）或blur。模糊背景要求image_fit=contain。文字保持清晰。 cover: 圖片縮放填充框架，居中 — 邊緣被裁剪。 |
| bg_color | string | "black" | background_mode=solid: 圖像未填滿目標解析度時的背景顏色。 |
| background_mode | string | "solid" | solid（預設）或blur。模糊背景要求image_fit=contain。文字保持清晰。 |
| blur_strength | number | 20 | 1至50的數值，預設20。僅對背景套用高斯模糊。 |
| enable_image_motion | bool | false | 啟用照片動畫。false時圖像保持靜態。 |
| image_motion_effect | string | "ken_burns" | 動畫效果。接受的值：zoom_in、zoom_out、pan_left_to_right、ken_burns等。 |
| motion_intensity | float | 1.0 | 照片動畫強度（0.25-2.0）。乘以縮放幅度和平移速度。 |
| text_effect | string | "none" | 文字疊加動畫。接受的值：none、fade_in、slide_up、bounce。 |
| text_effect_intensity | float | 1.0 | 文字動畫強度（0.25-2.0）。text_effect為none時忽略。 |
| text_border_width | int | 0 | 字元周圍黑色外框的厚度（像素），0 = 停用。 |
| text_border_color | string | "black" | 文字描邊的顏色（格式同 text_color，預設 "black"）。當 text_border_width > 0 時生效。 |
| text_mode | string | "static" | 文字顯示模式。static（預設）：從第一幀起顯示全文。word_by_word：按 word_reveal_speed 的速率逐字顯示。與 text_effect 互斥：若 text_mode=word_by_word，text_effect 將被忽略。 "karaoke"：文字隨音訊節奏逐頁變色（最多 1,000 個字元）。搭配 voice 時逐詞同步，否則依詞的長度分配到整段音訊。 |
| word_reveal_speed | float | 1.5 | 逐字顯示速度，單位為字/秒（0.3–5.0，預設 1.5）。僅在 text_mode=word_by_word 時使用。與 OpenAI TTS 同步的建議值：2.0。 |
| word_anim | string | "none" | 每個單字出現的動畫。none（預設）：即時顯示。fade：每個新單字以0.2秒淡入並與前一塊交叉淡化。僅在 text_mode=word_by_word 時有效。 |
| karaoke_style | string | "fill" | 卡拉OK樣式：fill（已讀的詞變為醒目提示顏色）、sweep（每個詞逐漸填滿；由右向左書寫的文字以整詞為單位）或 highlight（僅目前的詞變色）。 |
| highlight_color | string | "#FFD200" | 卡拉OK模式下已讀詞 / 目前詞的顏色（格式同 text_color）。 |
| karaoke_lines | int | 2 | 卡拉OK模式下每頁顯示的行數（1–4）。 |
| voice | string | "" | 語音 ID（與 text_to_mp3 相同的清單，例如 zh-TW-HsiaoChenNeural）：在同一工作中由 text 生成語音。此時 image_to_video 只需要圖片（同時上傳的 MP3 會被拒絕）。卡拉OK模式下每個詞都與語音同步。 |
| voice_rate | int | 0 | 生成語音的語速，以 % 表示（−50 至 +50）。 |
使用您自己的時間軸製作卡拉OK（SRT / LRC）
在 timings 欄位中傳送 SRT 或 LRC 檔案：每一行在各自的時間出現，並構成卡拉OK的一頁（最多 500 行、5,000 個字元）。SRT：行在結束時間消失。LRC：行一直顯示到下一行（空行會結束它）；支援 [offset:] 與增強型 LRC 的逐詞時間 <mm:ss.xx>，否則每行依其長度分配。在 add_text 中，時間以影片開頭為準，並依 text_start 位移。
# lyrics.srt
1
00:00:01,000 --> 00:00:03,500
First line of the song
2
00:00:04,000 --> 00:00:07,200
Second line, on its own page
# lyrics.lrc — enhanced LRC: optional per-word times <mm:ss.xx>
[00:01.00]<00:01.00>First <00:01.60>line <00:02.10>here
[00:04.00]Second line
[00:07.50]
options 參數 — overlay_video 模式
均為選用。上傳順序很重要：第一個檔案是主影片（背景），第二個檔案是疊加影片（前景）。使用 chroma_key 可去除疊加影片的綠幕背景。
| 鍵 | 類型 | 預設值 | 描述 |
|---|---|---|---|
| position | string | "bottom-right" | 疊加影片的放置位置：top-left、top-right、bottom-left、bottom-right 或 center。 |
| scale | float | 0.30 | 疊加影片寬度佔主影片寬度的比例。0.25 = 25%。範圍：0.05–1.0。 |
| opacity | float | 1.0 | 疊加影片的透明度。1.0 = 完全不透明，0.0 = 不可見。 |
| margin | int | 10 | 疊加影片與畫面邊緣的像素距離。當 position=center 時忽略。範圍：0–200。 |
| audio | string | "main" | 保留哪條音軌。main：僅主影片音訊。overlay：僅疊加音訊。mix：兩者混合。 |
| chroma_key | bool | false | 設為 true 可去除疊加影片的純綠色(#00FF00)背景 — 適用於綠幕前拍攝的攝影機或動畫。 |
| chroma_similarity | float | 0.20 | 綠幕容差。低 = 嚴格匹配。高 = 更廣泛去除。建議：數位綠 0.10–0.20，實體螢幕 0.25–0.45。範圍：0.01–0.60。 |
options 參數 — add_text 模式
文字為必填項。預設保留影片原始格式、影格率與音訊。output_format可搭配image_fit、bg_color與background_mode調整畫布。width、height、fps及照片運動選項仍會忽略。影片最長15分鐘。
{"text":"Hello","output_format":"portrait","image_fit":"contain","background_mode":"blur","blur_strength":20}| 鍵 | 類型 | 預設值 | 描述 |
|---|---|---|---|
| text | string | 是 | 要疊加的文字。必填，1–200 個字元。 |
| text_start | float | 0 | 文字出現的秒數（≥ 0）。必須早於影片結束時間。 |
| text_duration | float | 0 | 文字保持可見的時間，單位為秒（0.1–3600）。0 = 直到影片結束。 |
| font | string | "default" | 文字字型，依識別碼指定。可用值：default, dejavu-sans-bold, dejavu-serif, liberation-serif, dejavu-mono, amiri, noto-sans-sc (简体中文), noto-sans-tc (繁體中文), noto-sans-jp (日本語), noto-sans-kr (한국어), noto-sans-hebrew (עברית), noto-sans-thai (ไทย)。default = 標準字型（支援表情符號）；amiri = Naskh 字型，適合阿拉伯文文字。其他任何值都會回傳 invalid_option 錯誤。表情符號僅在 default 下顯示。 |
| font_size | int | 60 | 字型大小以短邊為 1080 px 的影片為基準，並會自動縮放至實際解析度——相同數值在 720p 與 4K 下的視覺效果一致。範圍：10–300。 |
| fade_duration | float | 0.5 | 文字（而非影片）的淡入/淡出時間，單位為秒。範圍：0–2。 |
| text_color, box, box_color, text_position, text_border_width, text_border_color, text_effect, text_effect_intensity, text_mode, word_reveal_speed, word_anim, karaoke_style, highlight_color, karaoke_lines, voice, voice_rate | — | — | 與 image_to_video 相同（見上表）。 |
| original_volume | float | 0.3 | 使用 voice 時：語音下方影片原聲的音量（0–2，預設 0.3；0 = 取代）。語音從 text_start 開始；文字一直顯示到語音結束，如果超出影片結尾，將定格最後一個畫面。 |
| background_mode | string | "solid" | solid（預設）或blur。模糊背景要求image_fit=contain。文字保持清晰。 |
| blur_strength | number | 20 | 1至50的數值，預設20。僅對背景套用高斯模糊。 |
| output_format | string | "original" | 僅限add_text：original（預設）、portrait（1080×1920）、square（1080×1080）、landscape（1920×1080）。模糊背景要求使用original以外的格式。 |
| image_fit | string | "contain" | contain: 完整顯示圖片或影片，並以所選背景填滿空白區域。 solid（預設）或blur。模糊背景要求image_fit=contain。文字保持清晰。 cover: 圖片縮放填充框架，居中 — 邊緣被裁剪。 |
| bg_color | string | "black" | background_mode=solid: 圖像未填滿目標解析度時的背景顏色。 |
options參數 — 音訊編輯（mix_audio）
僅在mode=mix_audio時可用。add_audio時忽略。
| 鍵 | 類型 | 預設值 | 描述 |
|---|---|---|---|
| mp3_volume | float | 1.0 | 疊加MP3的音量（0.0 = 靜音，1.0 = 原始音量，2.0 = 雙倍）。 |
text_to_mp3 模式 — 直接參數（無 options JSON）
與其他模式不同，這些欄位是直接作為表單欄位傳送，而不是放在 options JSON 物件內。只有 text 是必填的。
| 鍵 | 類型 | 預設值 | 描述 |
|---|---|---|---|
| text | string | — | 要轉換為語音的文字。必填。最多 5,000 個字元。 |
| lang | string | "en" | 當 voice 缺少或無效時用於選擇預設語音的語言代碼。網站 20 種語言之一（見下表）。未知時會回退到 en。 |
| voice | string | 自動 | edge-tts 語音 ID（見下表）。若缺少或無效，將自動使用 lang 的第一個語音。 |
| slow | bool | false | 設為 true（或 1）可將語速降低 25%。其他任何值都視為 false。 |
不需要上傳檔案：與其他模式不同，
text_to_mp3 不需要 videos[]。將 mode=text_to_mp3 與 text / lang / voice / slow 作為一般表單欄位一起傳送。可用語音（edge-tts, Microsoft Neural），依語言代碼分組：
| 語言 | 可用語音 |
|---|---|
en |
en-US-AvaNeural, en-US-AndrewNeural, en-GB-LibbyNeural, en-AU-NatashaNeural, en-AU-WilliamMultilingualNeural |
fr |
fr-FR-DeniseNeural, fr-FR-HenriNeural, fr-FR-EloiseNeural, fr-CA-SylvieNeural, fr-CA-ThierryNeural |
es |
es-ES-ElviraNeural, es-ES-AlvaroNeural, es-MX-DaliaNeural, es-AR-ElenaNeural, es-AR-TomasNeural |
ar |
ar-SA-ZariyahNeural, ar-SA-HamedNeural, ar-EG-SalmaNeural, ar-MA-MounaNeural, ar-MA-JamalNeural |
pt |
pt-BR-FranciscaNeural, pt-BR-AntonioNeural, pt-PT-RaquelNeural |
de |
de-DE-KatjaNeural, de-DE-ConradNeural, de-DE-AmalaNeural, de-AT-IngridNeural, de-AT-JonasNeural |
it |
it-IT-ElsaNeural, it-IT-DiegoNeural, it-IT-IsabellaNeural |
nl |
nl-NL-ColetteNeural, nl-NL-MaartenNeural, nl-BE-DenaNeural, nl-BE-ArnaudNeural |
ru |
ru-RU-SvetlanaNeural, ru-RU-DmitryNeural |
tr |
tr-TR-EmelNeural, tr-TR-AhmetNeural |
hi |
hi-IN-SwaraNeural, hi-IN-MadhurNeural |
bn |
bn-IN-TanishaaNeural, bn-IN-BashkarNeural, bn-BD-NabanitaNeural, bn-BD-PradeepNeural |
ur |
ur-PK-UzmaNeural, ur-PK-AsadNeural, ur-IN-GulNeural, ur-IN-SalmanNeural |
id |
id-ID-GadisNeural, id-ID-ArdiNeural |
ja |
ja-JP-NanamiNeural, ja-JP-KeitaNeural |
ko |
ko-KR-SunHiNeural, ko-KR-InJoonNeural |
zh-CN |
zh-CN-XiaoxiaoNeural, zh-CN-YunxiNeural, zh-CN-XiaoyiNeural |
zh-TW |
zh-TW-HsiaoChenNeural, zh-TW-YunJheNeural |
vi |
vi-VN-HoaiMyNeural, vi-VN-NamMinhNeural |
pl |
pl-PL-ZofiaNeural, pl-PL-MarekNeural |
成功回應（HTTP 200）
{
"success": true,
"job_id": "a3f1c8d2e5b09471...",
"mode": "fusion", // "fusion" | "add_audio" | "mix_audio" | "image_to_video" | "overlay_video" | "add_text" | "text_to_mp3"
"file_count": 2,
"transition": null,
"quota_used": 1,
"quota_remaining": 9,
"status_url": "https://rapidvideomaker.com/api/v1/jobs.php?job_id=a3f1c8..."
}
對於
text_to_mp3，回應中沒有 file_count 或 transition 欄位（未上傳任何檔案）——其餘相同：job_id、quota_used、quota_remaining、status_url、webhook_secret。curl範例 — 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"
# background_mode : "solid" | "blur" (blur requires contain)
# blur_strength : 1–50, default 20
# 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 — outline around characters (0 = disabled)
# text_border_color : outline color, default "black" (e.g. "#FF3366", "white@0.8")
# 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)
含生成語音的卡拉OK文字（image_to_video，不需 MP3）
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@scene.jpg" \
-F "mode=image_to_video" \
-F 'options={"text":"Every word lights up as the voice reads it.","voice":"en-US-AvaNeural","text_mode":"karaoke","karaoke_style":"sweep","highlight_color":"#FFD200","karaoke_lines":2,"text_position":"bottom","font_size":72}'
# no MP3: the voice is generated from "text" and gives the timing of every word
# text_mode="karaoke" : text up to 1000 characters, shown page by page (karaoke_lines: 1–4)
# karaoke_style : "fill" (default) | "sweep" | "highlight"
# voice_rate : -50…+50 (%), default 0
# with your own MP3 (no "voice"): karaoke timing is spread over the audio by word length
# add_text: same options + "original_volume" (0–2, default 0.3) = original sound under the voice
使用 SRT 檔案的卡拉OK（image_to_video + 您的 MP3）
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@cover.jpg" \
-F "videos[]=@song.mp3" \
-F "timings=@lyrics.srt" \
-F "mode=image_to_video" \
-F 'options={"karaoke_style":"sweep","karaoke_lines":2,"text_position":"bottom","font_size":72}'
# timings : SRT or LRC file (200 KB max), or its content as a plain text field: -F "timings=<lyrics.lrc"
# the displayed text comes from the file ("text" is ignored), text_mode is forced to "karaoke"
# not compatible with "voice" (the timings follow your own audio)
# add_text: times are relative to the video start, shifted by "text_start"
curl範例 — 音訊編輯
# 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)
curl 範例 — 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)
curl 範例 — add_text 模式
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "videos[]=@my_video.mp4" \
-F "mode=add_text" \
-F 'options={"text":"Hello world","text_position":"bottom","font_size":72,"text_color":"#ffd700","text_start":2,"text_duration":5,"text_effect":"slide_up"}'
# text : required, 1–200 characters
# text_start : second at which the text appears (default 0)
# text_duration : seconds the text stays visible, 0 = until the end (default 0)
# the video keeps its resolution, frame rate and audio track
curl範例 — 視訊合併
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"
curl 範例 — text_to_mp3 模式
# No file upload — text + lang + voice as plain form fields
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "mode=text_to_mp3" \
-F "text=Welcome to Rapid Video Maker." \
-F "lang=en" \
-F "voice=en-US-AvaNeural" \
-F "slow=false"
# voice omitted or invalid -> falls back to the first voice of "lang"
curl -X POST https://rapidvideomaker.com/api/v1/render.php \
-H "Authorization: Bearer rvm_your_token" \
-F "mode=text_to_mp3" \
-F "text=Bienvenue sur Rapid Video Maker." \
-F "lang=fr"
GET
/api/v1/jobs.php?job_id=<hex32>
任務狀態
狀態包含實際階段和已用時間。估計僅供參考；用戶端逾時不代表工作失敗。請繼續查詢同一工作ID。檔案在完成兩小時後到期。
可能的狀態
| 狀態 | 含義 | 額外欄位 |
|---|---|---|
| queued | 在佇列中，尚未處理 | queue_position, queue_total, eta_minutes |
| processing | FFmpeg處理中 | processing_stage, processing_elapsed_seconds, stage_elapsed_seconds, last_activity_at, processed_media_seconds, eta_overrun |
| ready | 已完成 — 檔案可用 | download_url, media_available, created_at, expires_at |
| error | 處理失敗 | error (message), quota_refund_status: pending | confirmed | not_required |
| cancelled | 已取消 | quota_refund_status: pending | confirmed | not_required |
按狀態的回應
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"
}
curl範例
curl -H "Authorization: Bearer rvm_your_token" \
"https://rapidvideomaker.com/api/v1/jobs.php?job_id=a3f1c8..."
GET
/api/v1/jobs.php
列出使用此權杖建立的所有工作（分頁，依日期由新到舊）
公共參數（multipart/form-data）
| 參數 | 類型 | 預設值 | 描述 |
|---|---|---|---|
page | integer | 1 | 頁碼（從 1 開始） |
limit | integer | 20 | 每頁結果數（最多 50，預設 20） |
按狀態的回應
{
"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
}
GET
/api/download.php?job_id=<hex32>
下載最終檔案
以串流形式傳輸最終檔案。影片模式的Content-Type為video/mp4，text_to_mp3則為audio/mpeg。不需要令牌。僅在狀態為ready時可用。
檔案在任務完成後保留2小時，然後刪除。狀態變為ready後請立即下載。
可選參數
| 參數 | 描述 |
|---|---|
| filename | 下載檔案的建議名稱（例如：my-video.mp4） |
| preview | 設為1可內嵌播放（省略Content-Disposition: attachment）而非觸發下載——用於瀏覽器內預覽。 |
curl範例
curl -o "output.mp4" \
"https://rapidvideomaker.com/api/download.php?job_id=a3f1c8...&filename=output.mp4"
Webhooks
Webhook是輪詢的替代方案：不是每隔X秒檢查狀態，而是提供URL，伺服器在任務完成時自動通知您。
運作原理
- 在POST到
/api/v1/render.php時傳入callback_url - 回應包含
webhook_secret— 儲存它以驗證簽章 - 當任務達到
ready或error時，伺服器向您的URL發送已簽章的JSONPOST - 使用
HMAC-SHA256(webhook_secret, raw_body)驗證簽章
限制：
callback_url必須是可公開存取的URL（http或https）。私有、回環和保留IP位址在伺服器端被封鎖。逾時：10秒。 收到的有效載荷
成功（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"
}
失敗（error）
{
"job_id": "a3f1c8...",
"status": "error",
"error": "FFmpeg xfade failed:...",
"timestamp": "2026-04-04T12:00:00+00:00"
}
伺服器發送的標頭
| 標頭 | 值 |
|---|---|
| Content-Type | application/json |
| X-RVM-Signature | sha256=<hmac_hex> — 原始主體的HMAC-SHA256簽章 |
| X-RVM-Job-Id | 相關的job_id |
簽章驗證
# 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()
錯誤代碼
| HTTP | JSON程式碼 | 原因 |
|---|---|---|
| 401 | unauthorized | 令牌缺失、無效或已撤銷 |
| 400 | missing_files | 未收到檔案 |
| 400 | too_few_files | 發送的檔案少於2個 |
| 400 | too_many_files | 發送的檔案超過20個 |
| 400 | invalid_mime | 不支援的檔案 — 僅接受MP4、MP3和JPG/PNG |
| 400 | wrong_file_count | 檔案數量與所選模式不符 |
| 400 | wrong_file_types | 檔案類型與所選模式不符 |
| 400 | invalid_file_combination | 沒有指定模式的檔案組合不符合任何支援的模式 |
| 400 | invalid_options | options欄位不是有效的JSON |
| 400 | invalid_option | options中的某個值無效 |
| 400 | file_too_large | 檔案超過500 MB |
| 400 | text_required | 缺少 options.text 欄位或其為空（add_text 模式） |
| 400 | video_too_long | 影片超過 15 分鐘（add_text 模式） |
| 400 | text_start_out_of_range | text_start 超出影片結尾 |
| 400 | invalid_voice | 未知的 voice ID。 |
| 400 | invalid_timings | 無法讀取時間軸檔案（格式無法辨識、沒有帶時間的行、結束早於開始、過長等）。 |
| 400 | invalid_order | order陣列不是有效的排列 |
| 400 | invalid_job_id | job_id格式不正確（必須是32個字元的十六進位） |
| 404 | job_not_found | 未找到任務 — job_id未知或從未存在 |
| 410 | job_expired | 任務已過期 — 曾經存在但2小時復原視窗已過 |
| 429 | quota_exceeded | 已達到每天20個成功任務的限制 |
| 429 | rate_limited | /api/v1/jobs.php每分鐘超過12次呼叫 |
| 500 | server_error | 內部伺服器錯誤 |
整合範例
各模式範例 — 使用pip install requests安裝requests。
公共設定
import requests, time, sys, json
API_BASE = "https://rapidvideomaker.com"
API_TOKEN = "rvm_your_token_here"
HEADERS = {"Authorization": f"Bearer {API_TOKEN}"}
image_to_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"
"background_mode": "solid", # or "blur" with contain
"blur_strength": 20,
"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"
}),
},
)
音訊編輯
# 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
)
overlay_video 模式 — 畫中畫
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
}),
},
)
add_text 模式 — 在影片上新增文字
with open("video.mp4", "rb") as fv:
resp = requests.post(
f"{API_BASE}/api/v1/render.php",
headers=HEADERS,
files=[("videos[]", ("video.mp4", fv, "video/mp4"))],
data={
"mode": "add_text",
"options": json.dumps({
"text": "Hello world", # required
"text_position": "bottom", # center | top | bottom
"font": "amiri", # font id (see the table above)
"font_size": 72,
"text_start": 2, # appears at 2 s
"text_duration": 5, # stays 5 s (0 = until the end)
}),
},
)
視訊合併
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"},
)
text_to_mp3 模式 — 文字轉語音
# No files — text + lang (+ optional voice / slow) as form fields
resp = requests.post(
f"{API_BASE}/api/v1/render.php",
headers=HEADERS,
data={
"mode": "text_to_mp3",
"text": "Welcome to Rapid Video Maker.",
"lang": "en", # one of the 20 site language codes
"voice": "en-US-AvaNeural", # optional — falls back to the first voice of "lang"
"slow": "false", # "true" = -25% speech rate
},
)
輪詢 + 下載（所有模式通用）
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")
n8n中的兩種方法：輪詢（狀態循環）或Webhook（伺服器呼叫n8n）。推薦Webhook。
方法A — Webhook（推薦）
僅3個節點，無循環。
節點1 — Webhook觸發器
新增Webhook節點作為工作流程輸入（方法POST）。
節點2 — 建立任務（HTTP請求）
| 方法 | POST |
| URL | https://rapidvideomaker.com/api/v1/render.php |
| 認證 | Header Auth — Authorization: Bearer rvm_… |
| 請求體內容類型 | Form-Data Multipart |
| Body params | 每個片段的二進位欄位videos[] + 文字欄位callback_url |
將回應中的webhook_secret儲存在工作流程變數中以驗證簽章。
節點3 — 處理結果（在Webhook觸發的工作流程中）
當n8n收到伺服器的POST時，$json.status為ready或error。
驗證簽章：將
{{ $headers['x-rvm-signature'] }}與您的webhook_secret的HMAC-SHA256進行比較。方法B — 輪詢（無Webhook）
5個節點，每10秒狀態循環。
節點1 — 建立任務 — 同上設定，無callback_url。
節點2 — 等待 — 10秒。
節點3 — 輪詢狀態（HTTP請求GET）
| URL | https://rapidvideomaker.com/api/v1/jobs.php |
| 查詢參數 | job_id = {{ $('節點1').item.json.job_id }} |
| 認證 | 標頭認證 — 相同令牌 |
節點4 — If：{{ $json.status }} === 'ready' → true：節點5 / false：返回節點2。
在Set節點中新增迭代計數器，以在60次嘗試後退出循環，避免無限循環。
節點5 — 下載：在{{ $json.download_url }}上發起HTTP請求GET。
步驟1 — 建立任務（選擇模式）
# 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"
步驟2 — 輪詢
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
步驟3 — 下載
DOWNLOAD_URL=$(echo $STATUS | grep -o '"download_url":"[^"]*"' | cut -d'"' -f4)
curl -o output.mp4 "$DOWNLOAD_URL"
最佳實踐
- 每隔5至10秒查詢同一工作。處理時間取決於模式和輸入大小。
- 狀態包含實際階段和已用時間。估計僅供參考；用戶端逾時不代表工作失敗。請繼續查詢同一工作ID。檔案在完成兩小時後到期。
- 快速下載：狀態變為
ready時立即下載。任務完成後2小時刪除。 - 配額管理：檢查POST回應中的
quota_remaining。 - 網路錯誤：輪詢過程中出現網路錯誤時，等待並重試。
結果檔案在任務完成後保留2小時，之後自動刪除。