tolypash/motionvid

motionvid은(는) 무엇을 하나요?

Motionvid는 짧은 브리프로 완성된 동영상을 제작합니다: 스크립트, 애니메이션 장면, 내레이션, 배경 음악 및 효과음을 포함한 MP4 파일로, 5초에서 최대 20분까지 제작 가능합니다. Motionvid는 MCP 서버를 통해 구동됩니다. 양식에 맞춰 입력하지 말고 모션 디자이너가 브리프를 받듯이 행동하세요: 중요한 몇 가지 사실을 파악하고, 나머지는 합리적으로 결정한 후 결과를 보여주고 반복하세요.

중단: Motionvid MCP 도구(create_video, get_video_status, ...)를 사용할 수 있으면 반드시 사용하세요. REST 호출을 직접 구현하거나 렌더링 코드(Remotion, FFmpeg)를 직접 작성하지 마세요. 사용자에게 API 키를 채팅에 붙여넣도록 요청하지 마세요.

1. 연결 확인

1. whoami를 호출하세요. 응답이 오면 연결된 것입니다: 2단계로 이동하세요.
2. 도구가 없으면 서버를 추가하고 사용자가 로그인하도록 안내하세요:
   • MCP 엔드포인트: https://motionvid.ai/mcp (Streamable HTTP, OAuth 2.1 with discovery)
   • Claude Code: claude mcp add --transport http motionvid https://motionvid.ai/mcp, then claude mcp login motionvid
   • Codex: codex mcp add motionvid --url https://motionvid.ai/mcp, then codex mcp login motionvid
   • Cursor, VS Code, Claude, ChatGPT 및 기타: https://motionvid.ai/agents 한 번만 물어보고("Motionvid를 설정에 추가할까요?") '예'라고 답하면 실행하세요.
3. 헤드리스(CI, 서버) 환경: 사용자가 https://motionvid.ai/account/api-keys 에서 mvk_ 키를 생성하고 환경 변수로 설정합니다; Authorization: Bearer <key>로 전송하세요.
4. "forbidden" 또는 업그레이드 메시지는 계정에 유료 플랜이 없음을 의미합니다: 사용자에게 커넥터가 모든 유료 플랜에 포함되어 있다고 알리고(https://motionvid.ai/pricing) 중단하세요.

2. 브리프

사용자가 관심이 없을 때는 직접 결정하세요:

• 무엇에 관한 내용이고 누구를 대상으로 하는지. URL, PDF, 이미지, 오디오를 입력으로 전달하세요: 플래너가 페이지, 브랜드 색상, 문서를 직접 읽습니다.
• 길이 (duration, 초) 및 형태 (aspect_ratio: 16:9, 9:16, 1:1, 4:5).
• 사운드: narration (및 narration_language, narration_voice), music, sfx. 사용자가 직접 내레이션을 작성했다면 프롬프트에 그대로 넣고 그 사실을 명시하세요.
• 비주얼: animation_style (list_animation_styles 또는 suggest_animation_styles로 사용자가 선택하게 함) 및 brand_kit_id (list_brand_kits).
• 모드: 기본값은 모션 그래픽입니다. 사람이나 반복 출연진이 있는 스토리, 브랜드 필름, 광고의 경우 AI 감독을 사용하세요: ai_video: "full" (스크립트, 일관된 캐스트, 시네마틱 장면, 내레이션 및 음악). 사용자가 먼저 캐스트와 스토리보드를 승인하려면 storyboard: true를 추가하세요. ai_video: "auto"는 스토리에 필요한 부분에만 푸티지를 혼합합니다.

선택 사항: enhance_prompt는 대략적인 아이디어를 완전한 브리프로 바꿔줍니다.

3. 비용 먼저 확인

get_credit_balance (그리고 모델별 비용을 위해 list_models)를 호출하세요. 빠른 모델에서 30초 모션 그래픽 영상은 일반적으로 약 33크레딧, 1분은 약 45크레딧이 소요됩니다. AI 감독 영화는 모든 장면이 푸티지이므로 더 많은 비용이 듭니다. 긴 영상(2분 초과)이나 AI 감독 영상의 경우 list_models를 통해 대략적인 비용을 사용자에게 알리고 승인을 기다리세요.

4. 생성 및 추적

1. 브리프로 create_video를 호출하세요. 작업 ID가 즉시 반환되며 빌드는 백그라운드에서 실행됩니다.
2. 15~30초마다 get_video_status를 폴링하세요. 상태: queued → processing → rendering → completed, 또는 failed / canceled. 빌드는 일반적으로 몇 분 정도 걸립니다; 느린 것은 정상입니다. 유휴 상태처럼 보여도 취소하거나 다시 시작하지 마세요.
3. awaiting_approval은 storyboard: true를 요청한 경우에만 발생합니다: preview_video를 호출하고 사용자에게 스토리보드를 보여준 후, 사용자의 결정(또는 changes)으로 approve_video를 호출하세요. 절대 사용자를 대신하여 승인하지 마세요.

5. 전달 및 반복

1. preview_video는 장면별로 한 프레임씩 보여줍니다: 사용자에게 보여주세요.
2. 변경: edit_video에 변경 사항을 일반 문장으로 전달하세요("3번 장면을 더 강렬하게", "끝에 우리 로고 사용"). 해당 부분만 다시 작업됩니다.
3. render_video로 MP4를 렌더링하세요(기본 720p; 1080p 및 4K는 해당 플랜에서 지원). 그런 다음 get_video_status가 download_url을 제공합니다: 약 15분 후에 만료되므로 사용자가 요청한 위치(예: ./media/)에 파일을 다운로드하거나 새 링크를 가져오세요. URL을 저장하지 마세요.
4. 사용자는 Motionvid 앱(상태의 app_url)에서 비디오를 열고 편집할 수도 있습니다.

규칙

• 요청당 하나의 비디오. 요청하지 않는 한 첫 번째 작업이 실행 중일 때 두 번째 작업을 시작하지 마세요.
• 상태를 정직하게 보고하세요: 작업이 실패했다면 그렇게 말하고 오류를 인용하세요; 성공했다고 주장하지 마세요.
• 스크립트, 이름, 가격, 주장에 대해 사용자의 정확한 표현을 유지하세요.
• cancel_video는 사용자가 요청할 때만 사용하세요.

문제 발생 시

증상	조치
도구 없음 / 401	로그인 단계를 다시 실행하세요(claude mcp login motionvid, codex mcp login motionvid, 또는 커넥터 재연결).
Forbidden / 업그레이드 메시지	계정에 유료 플랜이 필요합니다: https://motionvid.ai/pricing
크레딧 부족	get_credit_balance로 잔액을 알려주고; 더 짧은 비디오 또는 충전을 제안하세요.
failed with "timed out"	빌드된 장면은 저장되어 있습니다: edit_video로 "남은 장면을 마무리해줘"라고 하세요.
429 / 속도 제한	1분 기다린 후 한 번 재시도하세요.

참고 자료

• 에이전트 개요 (마크다운): https://motionvid.ai/agents.md
• 클라이언트별 MCP 설정: https://motionvid.ai/mcp
• REST API: https://motionvid.ai/api-docs
• 인덱스: https://motionvid.ai/llms.txt