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/MOV), Edit audio (1 MP4/MOV + 1 MP3), Create a video (1 JPG/PNG + 1 MP3), Overlay video (2 MP4/MOV picture-in-picture). Processing is asynchronous: submit files, then poll for the result.

무료로 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를 반환합니다. 또는 이미지 1개 + options.text + options.voice: 음성은 텍스트로 생성되며 MP3가 필요 없습니다.

작업 대기 — 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

토큰은 회원 공간에서 사용할 수 있습니다 — 계정당 하나의 토큰, 등록 시 자동으로 생성됩니다.

할당량

각 회원 계정은 웹 인터페이스와 API 간에 공유되는 하루 20개의 요청을 갖습니다. 실패한 작업은 할당량을 소비하지 않습니다. 카운터는 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초입니다.

엔드포인트

Five modes, accessible via the mode field (omit mode with multiple MP4s to auto-detect 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`	JPG/PNG 1개 + MP3 1개 — 또는 JPG/PNG 1개 + 텍스트(`options.text` + `options.voice`): 음성 생성	정지 이미지와 내 MP3로 — 또는 음성이 생성되는(`options.voice`) 텍스트(`options.text`)만으로 — 영상을 만듭니다. 텍스트 오버레이(고정, 단어별, 가라오케), 페이드, 해상도, fps는 `options` 필드로 설정할 수 있습니다.
Overlay video	`overlay_video`	2 MP4/MOV	두 번째 동영상을 메인 동영상 위에 겹칩니다. 위치, 크기, 불투명도, 오디오는 `options` 필드로 설정 가능합니다.
텍스트 추가	`add_text`	MP4/MOV 1개	기존 동영상 위에 텍스트를 넣습니다(해상도, 프레임 속도, 오디오 유지). `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가 업로드되어도 `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`: 가라오케 타이밍 파일(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"	텍스트 글꼴이며 ID로 지정합니다. 허용되는 값: `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` = 낙스 글꼴로 아랍어 텍스트에 적합합니다. 그 외의 값은 `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"	가라오케 스타일: `fill`(읽은 단어가 강조 색상으로 바뀜), `sweep`(각 단어가 점차 채워짐, 오른쪽에서 왼쪽으로 쓰는 문자는 단어 단위), `highlight`(현재 단어만 색칠).
highlight_color	string	"#FFD200"	가라오케 모드에서 읽은 단어 / 현재 단어의 색상(`text_color`와 같은 형식).
karaoke_lines	int	2	가라오케 모드에서 페이지당 표시할 줄 수(1–4).
voice	string	""	음성 ID(`text_to_mp3`와 같은 목록, 예: `ko-KR-SunHiNeural`): 같은 작업에서 `text`로 음성을 생성합니다. 이 경우 `image_to_video`는 이미지만 필요합니다(MP3를 함께 보내면 거부됨). 가라오케 모드에서는 모든 단어가 음성에 동기화됩니다.
voice_rate	int	0	생성된 음성의 속도(%, −50~+50).

직접 만든 타이밍으로 가라오케(SRT / LRC)

timings 필드로 SRT 또는 LRC 파일을 보내세요. 각 줄은 자기 시점에 나타나 가라오케의 한 페이지가 됩니다(최대 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"	텍스트 글꼴이며 ID로 지정합니다. 허용되는 값: `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` = 낙스 글꼴로 아랍어 텍스트에 적합합니다. 그 외의 값은 `invalid_option` 오류를 반환합니다. 이모지는 `default`에서만 표시됩니다.
font_size	int	60	짧은 변이 1080px인 동영상을 기준으로 한 글꼴 크기이며 실제 해상도에 맞게 자동으로 조정됩니다. 같은 값이면 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	말하기 속도를 25% 늦추려면 `true`(또는 `1`)로 설정하세요. 다른 값은 모두 `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)

생성된 음성이 있는 가라오케 텍스트(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 파일로 가라오케(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"

상태에는 실제 단계와 경과 시간이 포함됩니다. 예상 시간은 참고용이며 클라이언트 시간 초과가 실패를 의미하지는 않습니다. 같은 작업 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..."

공통 매개변수 (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
}

최종 파일을 스트리밍합니다. Content-Type은 동영상 모드에서는 video/mp4, text_to_mp3에서는 audio/mpeg입니다. 토큰 불필요. 상태가 ready일 때만 사용 가능.

파일은 작업 완료 후 2시간 동안 보관되며 그 후 삭제됩니다. 상태가 ready가 되는 즉시 다운로드하세요.

선택적 매개변수

매개변수	설명
filename	다운로드할 파일의 권장 이름(예: `my-video.mp4`)
preview	다운로드를 시작하는 대신 인라인 재생을 하려면(`Content-Disposition: attachment` 생략) `1`로 설정하세요 — 브라우저 내 미리보기에 사용됩니다.

curl 예시

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

Webhooks

Webhook은 폴링의 대안입니다: X초마다 상태를 확인하는 대신 URL을 제공하면 서버가 작업 완료 시 자동으로 알립니다.

작동 방식

/api/v1/render.php에 대한 POST에 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	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자 16진수여야 함)
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 모드 — PIP (화면 속 화면)

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 노드에 반복 카운터를 추가하세요.

노드 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시간 동안 보관되며 그 후 자동으로 삭제됩니다.

API RapidVideoMaker

완전한 워크플로

인증

할당량

대기열

사용 가능한 전환 효과

엔드포인트

공통 매개변수 (multipart/form-data)

options 매개변수 — image_to_video 모드

직접 만든 타이밍으로 가라오케(SRT / LRC)

options 파라미터 — overlay_video 모드

options 매개변수 — add_text 모드

options 매개변수 — 오디오 편집(mix_audio)

text_to_mp3 모드 — 직접 파라미터(options JSON 없음)

성공 응답 (HTTP 200)

curl 예시 — image_to_video 모드

생성된 음성이 있는 가라오케 텍스트(image_to_video, MP3 없음)

SRT 파일로 가라오케(image_to_video + 직접 올린 MP3)

curl 예시 — 오디오 편집

curl 예시 — overlay_video 모드

curl 예시 — add_text 모드

curl 예시 — 비디오 병합

curl 예제 — text_to_mp3 모드

가능한 상태

상태별 응답

curl 예시

공통 매개변수 (multipart/form-data)

상태별 응답

선택적 매개변수

curl 예시

Webhooks

작동 방식

수신된 페이로드

서버가 전송하는 헤더

서명 확인

오류 코드

통합 예시

공통 구성

image_to_video 모드 — 이미지 + 오디오 → 비디오

오디오 편집

overlay_video 모드 — PIP (화면 속 화면)

add_text 모드 — 동영상에 텍스트 추가

비디오 병합

text_to_mp3 모드 — 텍스트 음성 변환

폴링 + 다운로드(모든 모드에 공통)

방법 A — Webhook(권장)

방법 B — 폴링(Webhook 없이)

1단계 — 작업 생성(모드 선택)

2단계 — 폴링

3단계 — 다운로드

모범 사례

`options` 매개변수 — image_to_video 모드

`options` 파라미터 — overlay_video 모드

`options` 매개변수 — add_text 모드

`options` 매개변수 — 오디오 편집(`mix_audio`)

`text_to_mp3` 모드 — 직접 파라미터(`options` JSON 없음)