API RapidVideoMaker

REST API 可從任何 HTTP 客戶端處理影片檔案——Python 腳本、n8n 工作流程、第三方工具。五種模式：合併影片（多個 MP4）、編輯音訊（1 MP4 + 1 MP3）、建立影片（1 JPG/PNG + 1 MP3）、影片疊加（2 MP4 畫中畫）。處理為非同步：提交檔案後輪詢結果。

免費取得您的API令牌

建立帳號以取得您的API令牌 — 每天包含20次請求。

建立免費帳號已有帳號？登入

完整工作流程

每個整合都遵循相同的4步驟序列：

建立任務 — POST /api/v1/render.php

使用Bearer令牌將文件作為multipart/form-data發送。1張JPG/PNG圖像 + 1個MP3 + mode=image_to_video → 視訊生成。1個MP4 + 1個MP3 → 音訊編輯。多個MP4 → 合併。伺服器返回唯一的job_id。

等待任務 — GET /api/v1/jobs.php?job_id=…

定期（每5-10秒）輪詢此端點。任務會經歷queued → processing → ready（或error）。

取得下載URL

當狀態變為ready時，回應包含可用的download_url欄位。

下載檔案 — GET /api/download.php?job_id=…

下載最終MP4。檔案在任務完成後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秒之間。

端點

五種模式，透過 mode 欄位指定（多個 MP4 省略 mode 自動偵測 fusion）：

用法	API模式	所需檔案	描述
合併視訊	`fusion`	2-20個MP4檔案	片段按提供的順序首尾相連組裝。片段之間可選擇性加入轉場效果。
編輯音訊	`add_audio` 或 `mix_audio`	1個MP4 + 1個MP3	取代或豐富視訊的音軌。視訊軌道永不重新編碼。 `add_audio` — 原始音訊被刪除並完全替換為MP3。 `mix_audio` — 原始音訊被保留，MP3被疊加。
建立視訊	`image_to_video`	1張JPG/PNG + 1個MP3	從靜態圖像和音訊檔案生成視訊。文字疊加、淡入淡出、解析度和fps可透過`options`欄位設定。
影片疊加	`overlay_video`	2 MP4	將第二個影片疊加在主影片上方。位置、大小、透明度和音訊可透過 `options` 欄位設定。
文字轉MP3	`text_to_mp3`	（僅文字）	將文字轉換為語音並返回MP3檔案。無需上傳檔案 — 將 `mode=text_to_mp3`、`text` 和 `lang` 作為表單欄位傳送。支援網站的全部20種語言。

嚴格驗證：每種模式需要精確的檔案數量和類型。add_audio和mix_audio只接受1個MP4 + 1個MP3。image_to_video只接受1張JPG/PNG + 1個MP3。

時長規則：在音訊和image_to_video模式下，結果時長鎖定為MP3時長。

公共參數（multipart/form-data）

欄位	類型	必填	描述
videos[]	File[]	是	要處理的檔案。根據模式不同：2-20個MP4，或1個MP4 + 1個MP3，或1張圖像（JPG/PNG）+ 1個MP3。每個檔案最大500 MB。
mode	string	*	`image_to_video` \| `add_audio` \| `mix_audio`。這三種模式必填。僅當所有檔案均為MP4時忽略（`fusion`）。
order	JSON		僅限`fusion`模式 — 定義片段順序的索引JSON陣列。
transition_type	string		僅限`fusion`模式。預設：`none`。
transition_duration	float		僅限`fusion`模式。時長0.2-2.0秒。預設：`0.5`。
options	JSON		僅限`image_to_video`模式 — 渲染參數的JSON物件。
callback_url	string		任務完成時呼叫的公開URL（http/https）。回應包含`webhook_secret`。

`options`參數 — image_to_video模式

全部可選。未提供的值 → 由工作程序套用預設值。

鍵	類型	預設值	描述
text	string	""	作為疊加顯示的文字。空 = 無文字。最多500個字元。
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` = 顯示完整圖像；`cover` = 縮放以填滿整個畫面。
bg_color	string	"black"	圖像未填滿目標解析度時的背景顏色。
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_mode	string	"static"	文字顯示模式。`static`（預設）：從第一幀起顯示全文。`word_by_word`：按 `word_reveal_speed` 的速率逐字顯示。與 `text_effect` 互斥：若 `text_mode=word_by_word`，`text_effect` 將被忽略。
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` 時有效。

`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`參數 — 音訊編輯（`mix_audio`）

僅在mode=mix_audio時可用。add_audio時忽略。

鍵	類型	預設值	描述
mp3_volume	float	1.0	疊加MP3的音量（0.0 = 靜音，1.0 = 原始音量，2.0 = 雙倍）。

成功回應（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..."
}

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"
# 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)

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範例 — 視訊合併

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"

可能的狀態

狀態	含義	額外欄位
queued	在佇列中，尚未處理	`queue_position`, `queue_total`, `eta_minutes`
processing	FFmpeg處理中	—
ready	已完成 — 檔案可用	`download_url`, `created_at`, `expires_at`
error	處理失敗	`error` (message)

按狀態的回應

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

公共參數（multipart/form-data）

apidocs_th_param	類型	預設值	apidocs_th_desc
`page`	integer	1	Page number (starts at 1)
`limit`	integer	20	Results per page (max 50, default 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
}

將已完成的 job（status=ready）發布到一個或多個社交帳戶。Token 必須屬於會員帳戶（不是管理員 token）。

前提條件： 使用此端點前，需先在會員區的發布頁面透過 OAuth 連接社群帳號（YouTube、TikTok）。每個帳號的 account_id 在該頁面顯示。

公共參數（multipart/form-data）

apidocs_th_param	類型	apidocs_th_required	apidocs_th_desc
`job_id`	string	apidocs_required	已完成影片的 job ID（hex 32 位字元）
`publications`	array	apidocs_required	發布物件陣列（最多 10 個）

發布物件

apidocs_th_param	類型	apidocs_th_required	apidocs_th_desc
`account_id`	integer	apidocs_required	已連接社群帳號的 ID — 在會員區發布頁面中查看
`title`	string	—	影片標題（最多 512 個字元）
`description`	string	—	影片描述（最多 5 000 個字元）
`tags`	string	—	逗號分隔的標籤（最多 1 024 個字元）
`visibility`	string	—	`public` \| `private` \| `unlisted` — 預設：public
`tiktok_mode`	string	—	`draft` \| `direct` — 僅 TikTok — 預設：direct
`tiktok_privacy`	string	direct 模式	僅 TikTok — direct 模式下必填
`allow_comment`	boolean	—	僅 TikTok — 允許評論
`allow_duet`	boolean	—	僅 TikTok — 允許合拍
`allow_stitch`	boolean	—	僅 TikTok — 允許拼接
`your_brand`	boolean	—	僅 TikTok — 有機推廣內容（「您的品牌」）。
`branded_content`	boolean	—	僅 TikTok — 品牌內容披露
`tiktok_cover_ms`	integer	—	僅 TikTok — 封面幀時間戳（毫秒，0–60 000，預設 1 000）

按狀態的回應

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

每條發布的錯誤代碼

apidocs_th_code	含義
`job_not_ready`	job 尚未完成
`mode_not_supported`	text_to_mp3 job 無法發布
`account_not_found`	帳戶未找到或已斷開連線
`tiktok_privacy_required`	direct 模式需要隱私等級
`publication_failed`	上傳過程中提供者回傳了錯誤

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"
      }
    ]
  }'

以串流形式返回最終MP4檔案（Content-Type: video/mp4）。不需要令牌。僅在狀態為ready時可用。

檔案在任務完成後保留2小時，然後刪除。狀態變為ready後請立即下載。

可選參數

參數	描述
filename	下載檔案的建議名稱（例如：`my-video.mp4`）

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發送已簽章的JSON POST
使用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	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"
                "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
            }),
        },
    )

視訊合併

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"},
    )

輪詢 + 下載（所有模式通用）

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"

最佳實踐

輪詢頻率：/api/v1/jobs.php端點每個令牌限制12次/分鐘。呼叫間隔至少5秒。
逾時：實作用戶端逾時（例如：10分鐘）。
快速下載：狀態變為ready時立即下載。任務完成後2小時刪除。
配額管理：檢查POST回應中的quota_remaining。
網路錯誤：輪詢過程中出現網路錯誤時，等待並重試。

結果檔案在任務完成後保留2小時，之後自動刪除。

API RapidVideoMaker

完整工作流程

認證

配額

佇列

可用轉場效果

端點

公共參數（multipart/form-data）

options參數 — image_to_video模式

options 參數 — overlay_video 模式

options參數 — 音訊編輯（mix_audio）

成功回應（HTTP 200）

curl範例 — image_to_video模式

curl範例 — 音訊編輯

curl 範例 — overlay_video 模式

curl範例 — 視訊合併

可能的狀態

按狀態的回應

curl範例

公共參數（multipart/form-data）

按狀態的回應

公共參數（multipart/form-data）

發布物件

按狀態的回應

每條發布的錯誤代碼

cURL 範例

可選參數

curl範例

Webhooks

運作原理

收到的有效載荷

伺服器發送的標頭

簽章驗證

錯誤代碼

整合範例

公共設定

image_to_video模式 — 圖像 + 音訊 → 視訊

音訊編輯

overlay_video 模式 — 畫中畫

視訊合併

輪詢 + 下載（所有模式通用）

方法A — Webhook（推薦）

方法B — 輪詢（無Webhook）

步驟1 — 建立任務（選擇模式）

步驟2 — 輪詢

步驟3 — 下載

最佳實踐

`options`參數 — image_to_video模式

`options` 參數 — overlay_video 模式

`options`參數 — 音訊編輯（`mix_audio`）