Revideo Render Endpoint 사용법

Midrender Render Endpoint는 Platform에 업로드한 Revideo 프로젝트를 HTTP API로 렌더 요청하는 구체적인 사용법을 다룬다.

---

🔑 인증

export MIDRENDER_API_KEY="mr_..."

모든 요청에 Bearer 토큰으로 전달:

curl https://api.midrender.com/v1/render \
  -H "Authorization: Bearer $MIDRENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

API Key는 Midrender 대시보드 → Settings → API Keys에서 발급. 한도/스코프 설정 가능.

---

📦 프로젝트 업로드

방법 A: ZIP 업로드 (간단)

# 프로젝트 디렉토리 zip (node_modules 제외)
zip -r my-project.zip src/ project.ts package.json -x "node_modules/*"

# 업로드
curl -X POST https://api.midrender.com/v1/projects \
  -H "Authorization: Bearer $MIDRENDER_API_KEY" \
  -F "file=@my-project.zip" \
  -F "name=my-project"
# -> { "id": "proj_abc123", "name": "my-project" }

방법 B: GitHub repo 연결 (권장)

대시보드에서 GitHub repo URL 등록 → main 브랜치 push마다 자동 빌드.

# .midrender.yml (repo 루트)
project: src/project.ts
node: 20

CI/CD 자동화 / 버전 관리 / 협업이 쉬워짐.

---

▶️ 렌더 요청

curl -X POST https://api.midrender.com/v1/render \
  -H "Authorization: Bearer $MIDRENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "variables": {
      "userName": "김철수",
      "plan": "pro",
      "city": "서울"
    },
    "settings": {
      "size": [1080, 1920],
      "fps": 30,
      "format": "mp4"
    },
    "webhookUrl": "https://myapp.com/callbacks/render"
  }'

응답:

{
  "jobId": "job_xyz789",
  "status": "queued",
  "estimatedSeconds": 18
}

---

📥 결과 받기 — 두 가지 방식

1) Polling

curl https://api.midrender.com/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer $MIDRENDER_API_KEY"

{
  "jobId": "job_xyz789",
  "status": "completed",     // queued | rendering | completed | failed
  "progress": 1.0,
  "output": {
    "url": "https://cdn.midrender.com/.../video.mp4",
    "durationMs": 17420,
    "size": 1832412
  }
}

2) Webhook (서버↔서버)

POST https://myapp.com/callbacks/render
{
  "jobId": "job_xyz789",
  "status": "completed",
  "output": { "url": "...", "durationMs": 17420 }
}

폴링은 단순, 웹훅은 리소스 효율적. 운영 환경에서는 웹훅 권장.

---

⚙️ Settings 옵션

필드	타입	기본	설명
size	[w, h]	[1920, 1080]	해상도
fps	number	30	프레임 레이트
format	'mp4' | 'webm'	'mp4'	컨테이너
quality	'draft' | 'standard' | 'high'	'standard'	인코딩 품질
audio	boolean	true	오디오 트랙 포함
watermark	string | null	null	워터마크 텍스트 (플랜별)

{
  "settings": {
    "size": [1080, 1920],
    "fps": 60,
    "format": "mp4",
    "quality": "high",
    "audio": true
  }
}

---

🚦 상태 머신

queued ──▶ rendering ──▶ completed
                  │
                  └──▶ failed

상태	의미	다음 액션
queued	큐 대기 중	잠시 후 다시 조회
rendering	렌더 중 (progress 0~1)	잠시 후
completed	완료 (output.url)	mp4 다운로드
failed	실패 (error 메시지)	에러 로그 확인 + 재시도

---

🛠️ 에러 처리

// 응답 (4xx, 5xx)
{
  "error": "invalid_variables",
  "message": "variable 'userName' is required",
  "details": { "missing": ["userName"] }
}

에러 코드	원인	해결
invalid_variables	필수 변수 누락	variables 검증
project_build_failed	project.ts 빌드 에러	로컬에서 npm run build 먼저
render_timeout	5분 초과 (기본)	영상 분할 또는 longer plan
quota_exceeded	월 한도 초과	플랜 업그레이드
internal_error	서버 측 문제	재시도 + status page 확인

---

💻 TypeScript 클라이언트 (예시)

async function render(projectId: string, variables: Record<string, any>) {
  const res = await fetch('https://api.midrender.com/v1/render', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.MIDRENDER_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({projectId, variables, settings: {size: [1080, 1920]}}),
  });
  if (!res.ok) throw new Error(`Render failed: ${res.status}`);
  const {jobId} = await res.json();

  // 폴링 (또는 webhook 사용)
  while (true) {
    const status = await fetch(`https://api.midrender.com/v1/jobs/${jobId}`, {
      headers: {'Authorization': `Bearer ${process.env.MIDRENDER_API_KEY}`},
    }).then(r => r.json());

    if (status.status === 'completed') return status.output.url;
    if (status.status === 'failed') throw new Error(status.error);
    await new Promise(r => setTimeout(r, 2000));
  }
}

---

🚀 다음 단계

작업	가이드
Platform 개요	Revideo Platform 소개
자체 호스팅	Revideo 렌더링 서비스 배포
도움말	Revideo Discord

---

🔗 공식 리소스

• 공식 문서: https://midrender.com/revideo/docs/platform/render-endpoint
• API 레퍼런스: https://midrender.com/docs/api
• 상태 페이지: https://status.midrender.com

상위 문서: ← Revideo 플랫폼 & 도움말 출처: Revideo 공식 문서 — Using your Render Endpoint 한글화 (2026-07-29) 공급사: Revideo (현 Midrender)

변경 이력

날짜	변경
2026-07-29	초안 작성 — Render Endpoint 인증/업로드/렌더/결과/에러 처리