API RapidVideoMaker

REST API 允许从任何 HTTP 客户端处理视频文件——Python 脚本、n8n 工作流、第三方工具。五种模式：合并视频（多个 MP4/MOV）、编辑音频（1 MP4/MOV + 1 MP3）、创建视频（1 JPG/PNG + 1 MP3）、视频叠加（2 MP4/MOV 画中画）。处理为异步：提交文件后轮询结果。

免费获取您的API令牌

创建账户以获取您的API令牌 — 每天包含20次请求。

创建免费账户已有账户？登录

完整工作流程

每个集成都遵循相同的4步序列：

创建任务 — 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。

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

定期（每5-10秒）轮询此端点。任务会经历queued → processing → ready（或error）。

获取下载URL

当状态变为ready时，响应包含可用的download_url字段。

下载文件 — 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秒之间。

端点

五种模式，通过 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	从静态图像和音频文件生成视频。文本叠加、淡入淡出、分辨率和fps可通过`options`字段配置。
视频叠加	`overlay_video`	2 MP4/MOV	将第二个视频叠加在主视频上方。位置、大小、透明度和音频可通过 `options` 字段配置。
文字转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。

时长规则：在音频和image_to_video模式下，结果时长锁定为MP3时长。

公共参数（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`字段，上传的文件必须完全匹配——否则请求将被拒绝。
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 = 双倍）。

`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`
`fr`	`fr-FR-DeniseNeural`, `fr-FR-HenriNeural`, `fr-FR-EloiseNeural`
`es`	`es-ES-ElviraNeural`, `es-ES-AlvaroNeural`, `es-MX-DaliaNeural`
`ar`	`ar-SA-ZariyahNeural`, `ar-SA-HamedNeural`, `ar-EG-SalmaNeural`
`pt`	`pt-BR-FranciscaNeural`, `pt-BR-AntonioNeural`, `pt-PT-RaquelNeural`
`de`	`de-DE-KatjaNeural`, `de-DE-ConradNeural`, `de-DE-AmalaNeural`
`it`	`it-IT-ElsaNeural`, `it-IT-DiegoNeural`, `it-IT-IsabellaNeural`
`nl`	`nl-NL-ColetteNeural`, `nl-NL-MaartenNeural`
`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`
`ur`	`ur-PK-UzmaNeural`, `ur-PK-AsadNeural`
`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" | "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"
# 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"

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"

可能的状态

状态	含义	额外字段
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）

参数	类型	默认值	描述
`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）

参数	类型	必填	描述
`job_id`	string	是	已完成视频的 job ID（hex 32 位字符）
`publications`	array	是	发布对象数组（最多 10 个）

发布对象

参数	类型	必填	描述
`account_id`	integer	是	已连接社交账号的 ID — 在会员区发布页面中查看
`title`	string	—	视频标题（最多 512 个字符）
`description`	string	—	视频描述（最多 5 000 个字符）
`tags`	string	—	逗号分隔的标签（最多 1 024 个字符）
`visibility`	string	—	`public` \| `private` \| `unlisted` — 默认：public
`tiktok_mode`	string	—	`draft` \| `direct` — 仅 TikTok — 默认：draft
`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"
    }
  ]
}

每条发布的错误代码

代码	含义
`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"
      }
    ]
  }'

以流的形式传输最终文件。视频模式的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发送签名的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"},
    )

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"

最佳实践

轮询频率：/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）

text_to_mp3 模式 — 直接参数（无 options JSON）

成功响应（HTTP 200）

curl示例 — image_to_video模式

curl示例 — 音频编辑

curl 示例 — overlay_video 模式

curl示例 — 视频合并

curl 示例 — text_to_mp3 模式

可能的状态

按状态的响应

curl示例

公共参数（multipart/form-data）

按状态的响应

公共参数（multipart/form-data）

发布对象

按状态的响应

每条发布的错误代码

cURL 示例

可选参数

curl示例

Webhooks

工作原理

接收到的有效载荷

服务器发送的标头

签名验证

错误代码

集成示例

公共配置

image_to_video模式 — 图像 + 音频 → 视频

音频编辑

overlay_video 模式 — 画中画

视频合并

text_to_mp3 模式 — 文本转语音

轮询 + 下载（所有模式通用）

方法A — Webhook（推荐）

方法B — 轮询（无Webhook）

步骤1 — 创建任务（选择模式）

步骤2 — 轮询

步骤3 — 下载

最佳实践

`options`参数 — image_to_video模式

`options` 参数 — overlay_video 模式

`options`参数 — 音频编辑（`mix_audio`）

`text_to_mp3` 模式 — 直接参数（无 `options` JSON）