Claude Opus 5.5와 Remotion: 코드 기반 제품 영상 제작의 전체 워크플로
Claude Opus 5.5가 Remotion 또는 HyperFrames 코드를 작성·수정하고, 로컬이나 CI가 재현 가능한 MP4를 렌더하도록 구성하는 실전 가이드입니다. 파라미터화, 검증, Batch API와 비용 경계도 함께 다룹니다.
목차
먼저 결론부터 말하면, Claude Opus 5.5와 Remotion 조합은 제품 설명, UI 애니메이션, 코드 walkthrough, 데이터 시각화, 출시 영상, 재사용 가능한 마케팅 템플릿에 잘 맞습니다. Opus 5.5가 요구사항을 이해하고 React/TypeScript 코드를 작성하거나 수정하며, Remotion이 그 코드를 프레임 단위로 렌더합니다. 둘 다 확산형 영상 모델은 아니므로 프롬프트 하나가 곧바로 사실적인 MP4를 반환하지는 않습니다.
배우, 사실적인 장소, 영화적 카메라 움직임, 코드로 안정적으로 정의하기 어려운 화면이 핵심이라면 그 소재는 촬영하거나 별도의 생성 단계에서 만드세요. 이후 Remotion 또는 HyperFrames로 자막, 전환, 브랜드 그래픽, 반복 가능한 조립을 처리할 수 있습니다.
이 글은 현재 공식 문서를 기준으로 한 실행 경로입니다. 성공 기준은 자신의 PC나 CI에서 실제로 MP4가 렌더되고 검증되는 것입니다. 확인되지 않은 SNS 데모, 고정 렌더 시간, 보편적인 영상 1개당 비용을 사실처럼 제시하지 않습니다.
1분 선택표
| 작업 | 먼저 볼 도구 | 이유 |
|---|---|---|
| 제품 투어, UI, 코드, 차트 | Remotion | React 구성 요소, props, 타임라인, 렌더 생태계가 성숙함 |
| HTML/CSS 모션과 Agent 중심 handoff | HyperFrames | React 없이 HTML을 직접 작성 가능 |
| 하나의 템플릿에서 여러 영상 | 둘 다 가능 | 콘텐츠를 파라미터화하면 결정론적 렌더 가능 |
| 사실적인 인물·장소·영화 장면 | 별도의 미디어 제작 단계 | 코드 영상의 자연스러운 영역이 아님 |
| 다시 쓰지 않을 짧은 영상 1개 | 최소 프로토타입 | Batch 플랫폼은 너무 이른 투자일 수 있음 |
핵심 질문은 “AI가 영상을 만들 수 있는가”가 아니라 각 프레임을 코드, 파일, 데이터, 시간으로 설명할 수 있는가입니다. 웹 화면, 슬라이드, 대시보드, 코드 편집기, 자막, 브랜드 애니메이션에 가까울수록 이 방식의 장점이 커집니다.
Claude Opus 5.5의 역할과 한계
Anthropic은 2026년 9월 22일 Claude Opus 5.5를 공개했습니다. 정확한 API 모델 ID는 claude-opus-5-5입니다. 이 워크플로에서는 다음을 맡길 수 있습니다.
- brief를 장면, 구성 요소, 시간, 검수 조건으로 나누기.
- Remotion 또는 HyperFrames의 여러 파일 수정하기.
- 하드코딩된 콘텐츠를 props, JSON, manifest로 옮기기.
- 타입 검사, preview, render를 실행하고 로그의 원인을 고치기.
- 여러 변형에서 디자인 규칙 유지하기.
중요한 경계는 모델의 결과가 텍스트, 코드, 패치이며 최종 MP4가 아니라는 점입니다. 실제 렌더는 로컬 PC, CI runner, 서버, Remotion Lambda 또는 HyperFrames 환경에서 진행됩니다. 모델 Token 비용과 CPU, Chrome, FFmpeg, 저장공간, 트래픽 비용을 분리해 계산해야 합니다.
프롬프트 전에 brief를 고정하기
검증 가능한 brief.md를 만드세요.
# 영상 브리프
- 목표: 사용자가 API 키를 만들고 첫 요청을 보내는 과정을 설명한다.
- 대상: 제품을 처음 평가하는 개발자.
- 형식: 1920x1080, 30 fps, 8초, 오디오 없음.
- Composition ID: ProductExplainer
- 장면:
1. 문제와 약속, 0–2초
2. 3단계 제품 흐름, 2–6초
3. 최종 결과와 CTA, 6–8초
- 입력: productName, headline, steps, accentColor, 스크린샷 경로
- 제약: 로컬 assets만 사용하고 렌더 중 네트워크 요청을 하지 않는다.
- 완료 조건:
- 텍스트가 안전 여백 안에 들어간다.
- 콘솔 오류가 없다.
- CLI에서 Composition을 MP4로 렌더할 수 있다.
- props.json만 바꿔 두 번째 변형을 렌더할 수 있다.해상도, FPS, 길이, Composition ID, 소재 경로, 네트워크 정책, 검증 명령은 Agent가 추측하지 않도록 입력으로 명시해야 합니다.
Remotion 공식 경로로 최소 프로젝트 만들기
Node.js와 Claude Code를 설치한 뒤 다음 명령을 실행합니다.
npx create-video --yes --blank my-video
cd my-video
npm install
npx remotion skills add
npm run dev별도 터미널에서 같은 저장소를 엽니다.
cd my-video
claude처음부터 전체 플랫폼을 요구하지 말고 원격 소재가 없는 8초짜리 Composition 하나만 요청합니다.
수정하기 전에 brief.md를 읽고 기존 Remotion 프로젝트를 점검하세요.
정확한 ID가 ProductExplainer인 Composition 하나를 만드세요.
1920x1080, 30 fps, 240 frames를 사용하세요.
React, CSS, inline SVG만으로 깔끔한 3장면 제품 설명 영상을 만드세요.
Composition은 productName, headline, steps, accentColor를 props로 받고,
Studio 미리보기를 위한 적절한 default props를 포함해야 합니다.
모든 텍스트를 120px 안전 여백 안에 두고 렌더 중 원격 assets를 가져오지 마세요.
각 frame이 결정적으로 재현되도록 frame 기반 Remotion API로 애니메이션하세요.
수정 후 변경한 파일, 미리보기 명령, 정확한 렌더 명령을 보고하세요.
렌더 명령이 exit code 0으로 끝나기 전에는 성공했다고 말하지 마세요.Composition ID를 고정하면 자동화가 안정됩니다. 프레임 기반 애니메이션은 재현성을 유지합니다. 첫 테스트를 로컬 소재로 제한하면 CORS, 네트워크, 만료 URL 문제를 분리할 수 있습니다.
Preview, render, 검증
Remotion Studio에서 ProductExplainer가 끝까지 재생되는지 확인한 뒤 실행합니다.
npx remotion render ProductExplainer out/product-explainer.mp4최소 성공 조건은 다음과 같습니다.
- 명령 종료 코드가 0.
out/product-explainer.mp4가 존재하고 재생 가능.- 잘린 텍스트, 빈 프레임, 누락된 소재가 없음.
- 터미널과 브라우저 콘솔에 미처리 예외가 없음.
- 두 번째 버전은 컴포넌트 수정 없이 props 변경만으로 렌더 가능.
메타데이터도 자동 검사합니다.
ffprobe -v error \
-show_entries stream=codec_name,width,height,r_frame_rate \
-show_entries format=duration \
-of json out/product-explainer.mp4CI는 이를 통해 길이 0, 잘못된 해상도, 영상 스트림이 없는 파일을 거부할 수 있습니다.
props로 템플릿 만들기
props.json을 만듭니다.
{
"productName": "Acme API",
"headline": "세 단계로 보내는 첫 요청",
"steps": [
"API 키 만들기",
"모델 선택하기",
"요청 보내기"
],
"accentColor": "#6D5EF9"
}렌더 명령:
npx remotion render ProductExplainer out/acme-api.mp4 --props=props.jsonRemotion은 Windows shell에서 inline JSON의 따옴표가 사라질 수 있다고 안내합니다. 파일 입력이 더 안전합니다. 다국어 버전에서는 컴포넌트를 복제하지 말고 표시와 콘텐츠를 분리합니다.
src/
components/
ProductExplainer.tsx
Root.tsx
content/
en.json
ru.json
de.json
public/
screenshots/
render-manifest.json컴포넌트는 시각과 동작, 언어 파일은 텍스트와 소재 경로, manifest는 locale·props·출력 파일명을 담당합니다.
렌더 실패를 진단하는 순서
먼저 상세 로그를 켭니다.
npx remotion render ProductExplainer out/debug.mp4 --log=verbose병렬 처리로 로그가 반복되면 임시로 한 스레드만 사용합니다.
npx remotion render ProductExplainer out/debug.mp4 \
--log=verbose \
--concurrency=1그다음 순서대로 확인합니다.
- 대소문자를 포함한 Composition ID 일치 여부.
- 외부 JSON 전에 default props로 렌더.
- 영상, 폰트, 차트, 복잡한 효과를 하나씩 제거.
- interactive browser와 headless Chrome의 차이, CORS, 인증서, GPU/WebGL 확인.
- 비동기 리소스 대기가 정상 종료되는지 확인.
- 명령, props, commit, 최초 원인 오류, 환경 버전을 보존.
Agent에게 다시 전달할 때는 반복 로그 전체가 아니라 정확한 명령과 첫 번째 원인을 주세요. 원인 설명, 최소 패치, 동일 검증 명령 재실행을 요구합니다.
Remotion, HyperFrames, 확산형 영상
HyperFrames는 HeyGen의 오픈소스 HTML 네이티브 영상 프레임워크입니다. HTML, CSS, 미디어, seek 가능한 애니메이션을 결정론적 MP4로 렌더합니다.
npx hyperframes init my-video
cd my-video
npx hyperframes preview
npx hyperframes render현재 README 요구사항은 Node.js 22+와 FFmpeg입니다. GSAP, CSS, Lottie, Three.js, Anime.js, WAAPI, 사용자 정의 adapter를 지원합니다.
| 기준 | Remotion | HyperFrames | 확산형 영상 |
|---|---|---|---|
| 작성 방식 | React/TypeScript | HTML/CSS/JS | 텍스트·이미지·영상 프롬프트 |
| 재현성 | 입력 고정 시 높음 | 설계상 높음 | 상대적으로 낮음 |
| 적합한 작업 | UI, 코드, 데이터, 복잡한 템플릿 | Web 모션, Agent handoff | 사실적 인물과 장면 |
| 파라미터 | props, 데이터, 컴포넌트 | data attributes, HTML, Script | 모델 설정과 소재 |
| 주요 비용 | 개발과 렌더 | 개발과 렌더 | 생성과 후반 작업 |
React 팀과 장기 운영 템플릿에는 Remotion, 읽기 쉬운 index.html로 충분한 Web형 표현에는 HyperFrames를 검토하세요. 사실적 영상은 별도로 만들고 코드 도구로 조립합니다.
대량 생성에서 API는 한 단계일 뿐
권장 구조:
브리프 / assets / 브랜드 규칙
↓
Claude API: 코드 또는 패치 생성·수정
↓
검증: schema, allowlist, typecheck, lint, 리뷰
↓
Remotion 또는 HyperFrames 렌더 workers
↓
ffprobe / 시각 검토 / 저장 / 게시모델 응답을 운영 서버에서 바로 실행하지 마세요. 쓰기 디렉터리를 제한하고, 비밀을 prompt에 넣지 않고, 의존성을 고정하고, 새 명령을 검토하고, 격리된 환경에서 빌드합니다. Anthropic Message Batches API는 Messages 요청을 비동기로 처리하며 영상 렌더 큐가 아닙니다.
API Key를 화면에 표시하지 않고 입력합니다.
read -rs ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
printf '\n'python -m pip install anthropicbriefs.json:
[
{
"id": "launch-en",
"brief": "content/en.json을 사용해 영어 출시 변형의 패치를 만드세요."
},
{
"id": "launch-de",
"brief": "content/de.json을 사용해 독일어 출시 변형의 패치를 만드세요."
}
]생성, ended까지 polling, custom_id별 저장을 모두 포함한 예시입니다. 결과 순서는 입력 순서와 다를 수 있습니다.
#!/usr/bin/env python3
import json
import time
from pathlib import Path
import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
MODEL = "claude-opus-5-5"
briefs = json.loads(Path("briefs.json").read_text(encoding="utf-8"))
client = anthropic.Anthropic()
requests = []
for item in briefs:
requests.append(
Request(
custom_id=item["id"],
params=MessageCreateParamsNonStreaming(
model=MODEL,
max_tokens=8000,
system=(
"코드 기반 영상 프로젝트를 유지보수합니다. "
"간결한 구현 계획과 unified diff를 반환하세요. "
"비밀 정보나 알 수 없는 코드를 내려받아 실행하는 명령을 포함하지 마세요."
),
messages=[{"role": "user", "content": item["brief"]}],
),
)
)
batch = client.messages.batches.create(requests=requests)
Path("batch-id.txt").write_text(batch.id, encoding="utf-8")
print(f"생성: {batch.id}")
while True:
current = client.messages.batches.retrieve(batch.id)
if current.processing_status == "ended":
break
print(f"처리 중: {current.request_counts}")
time.sleep(60)
out_dir = Path("batch-results")
out_dir.mkdir(exist_ok=True)
for result in client.messages.batches.results(batch.id):
outcome = result.result
if outcome.type == "succeeded":
text = "".join(
block.text for block in outcome.message.content if block.type == "text"
)
(out_dir / f"{result.custom_id}.txt").write_text(text, encoding="utf-8")
print(f"저장: {result.custom_id}")
else:
print(f"저장 안 됨: {result.custom_id} -> {outcome.type}")검토한 patch만 적용한 뒤 CI가 검증된 디렉터리를 렌더합니다.
for dir in variants/*; do
[ -d "$dir" ] || continue
(
cd "$dir"
npm ci
npx remotion render ProductExplainer \
"out/$(basename "$dir").mp4" \
--props=props.json
)
done현재 Batch 한도는 최대 100,000개 요청 또는 256 MB입니다. 대부분 1시간 이내에 끝나지만 최대 24시간 처리될 수 있고, 완료되지 않으면 expired가 됩니다. 결과는 생성 후 29일 동안 제공됩니다. custom_id로 연결하고 errored, canceled, expired는 실패로 처리합니다.
Token 유형별 비용 계산
2026년 9월 28일 확인, 백만 Token당 USD, 정확한 모델 ID claude-opus-5-5 기준입니다.
| 항목 | Anthropic 표준 | BetterToken 표준 실효가 | 정의 |
|---|---|---|---|
| 일반 입력 | $4.00 | $2.72 | Cache에서 읽지 않은 입력 |
| 출력 | $20.00 | $13.60 | 모델이 생성한 Token |
| 5분 Cache 쓰기 | $5.00 | $3.40 | 5분 Cache 최초 기록 |
| 1시간 Cache 쓰기 | $8.00 | $5.44 | 1시간 Cache 최초 기록 |
| Cache 읽기/갱신 | $0.20 | $0.136 | 저장된 prefix 재사용 |
BetterToken 공개 설정은 tier 기본 가격에 현재 Claude 그룹 배율 0.68을 곱합니다. model_ratio=0은 무료가 아닙니다. 사용 전에 BetterToken 가격과 Anthropic 가격을 다시 확인하세요.
model_cost =
input_tokens / 1,000,000 × input_price
+ output_tokens / 1,000,000 × output_price
+ cache_write_5m_tokens / 1,000,000 × cache_write_5m_price
+ cache_write_1h_tokens / 1,000,000 × cache_write_1h_price
+ cache_read_tokens / 1,000,000 × cache_read_price20개 brief가 각각 입력 30,000 Token, 출력 8,000 Token, Cache 없음이라면:
- Anthropic 표준 동기:
$5.60 - Anthropic Batch: 입력·출력 50% 할인으로 약
$2.80 - BetterToken 표준 실효 동기:
$3.808
이는 동일 Token 사용량의 모델 비용 비교일 뿐 영상 1개의 고정 가격이 아닙니다. 재시도, CPU/GPU, Chrome, 저장공간, 트래픽, 소재 제작, 사람의 검수는 별도입니다.
이 워크플로에서 BetterToken의 경계
BetterToken은 Claude Code용 Anthropic-compatible 경로로 검토할 수 있습니다. 현재 Claude Code Base URL은 https://bettertoken.ai이며, 사용자가 자신의 계정과 API Key를 만듭니다. Claude.ai 또는 Claude Max 구독이 아닙니다.
/v1/messages 지원만으로 BetterToken이 Message Batches와 호환된다는 점을 증명할 수는 없습니다. 따라서 위 Batch 예시는 Anthropic 공식 API만 근거로 합니다. BetterToken이 Batch 계약, endpoint, 한도, 과금을 명시하기 전에는 Base URL만 바꿔 지원된다고 판단하지 마세요.
러시아 이용자는 러시아어 문서와 루블 결제를 사용할 수 있지만, 결제 수단, 최소 금액, 환율, 수수료, 반영 시간은 결제 화면 기준입니다.
운영 전 체크리스트
- 목적, 대상, 형식, 장면, 합격 조건이 있는 brief.
- 로컬 및 라이선스 확인 소재, 고정된 폰트와 Screenshot.
- 하나의 파라미터화된 Composition, 언어별 콘텐츠 분리.
- lockfile commit, CI에서
npm ci. - CLI render,
ffprobe, 시각 검수 통과. - 실패 시 명령, props, log, commit, 환경 저장.
- 정확한 모델 ID
claude-opus-5-5. - 입력, 출력, Cache를 별도 계측.
- Batch 전 1~2개 동기 request로 형식 확인.
custom_id로 결과 연결.- 모델 비용과 렌더 비용 분리.
다음 단계
같은 8초 brief를 Remotion Blank 프로젝트와 HyperFrames HTML로 각각 만드세요. 첫 유효 MP4까지 걸린 시간, 2차 버전 수정량, 10회 연속 렌더 실패율만 비교합니다. 그 결과에 따라 props, CI, Batch를 추가하세요.
재현 가능하고 검증되며 파라미터화된 영상 한 개를 먼저 만드는 것이 100개로 가는 가장 빠른 길입니다.
