힉스필드 CLI × 클로드 코드로 AI 영상 자동화 — 사진 1장으로 광고 만들기

터미널 한 줄에서 영상 한 개. 그리고 클로드 코드로 열 개. 이 글을 끝까지 읽으면, 당신 컴퓨터에서 영상이 실제로 나오는 구조를 손에 쥐게 됩니다.

들어가며 — 영상은 이제 '찍는 것'이 아니라 '시키는 것'

결론부터 말씀드릴게요. 이제 광고 영상은 카메라로 찍는 게 아니라 명령으로 시킵니다. 터미널에 한 줄을 치면 5초짜리 광고 클립이 나오고, 그걸 클로드 코드한테 맡기면 "다섯 개 만들어줘" 한 마디로 다섯 개가 폴더에 쌓여요.

마우스 클릭은 한 번도 없습니다. 좀 과장 같죠? 그래서 저희가 진짜로 해봤습니다. 정상록 대표 헤드샷 사진 한 장으로 약 18초짜리 세로 홍보 광고를 끝까지 만들어냈어요. 그 과정을 이 글 5장에 그대로 풀어둘게요.

1인 기업, 마케터, 콘텐츠 만드는 분이라면 이 한 문장이 와닿을 거예요. "영상 비용 때문에 못 만들던 걸, 이제 점심값으로 만든다." 자, 그럼 두 도구부터 소개하고 시작하죠.

1. 두 도구 — 영상 스튜디오와 '말 알아듣는 손'

비유로 먼저 잡고 갈게요.

• 힉스필드(Higgsfield) 는 AI 영상·이미지 스튜디오예요. 프롬프트(장면 설명)를 주면 영상을 뽑아주는 공장입니다. 보통 웹사이트에서 클릭으로 쓰는데, 우리가 주목할 건 이 공장에 명령어로 들어가는 뒷문, 바로 CLI(커맨드라인 도구)예요.
• 클로드 코드(Claude Code) 는 터미널 안에서 사람 말을 알아듣는 코딩 에이전트예요. "이거 다섯 개 만들어서 폴더에 정리해줘" 같은 한국어 부탁을 받아서, 실제 명령으로 바꿔 알아서 실행합니다.

쉽게 말하면 이래요. 힉스필드 CLI는 영상을 만드는 손이고, 클로드 코드는 그 손에게 뭘 할지 시키는 머리예요. 이 둘을 붙이는 게 오늘의 핵심입니다.

2. 왜 굳이 연결하나 — '2레이어' 구조

영상 하나는 힉스필드 웹사이트에서 클릭으로도 충분히 만들어요. 그런데 열 개, 백 개를 다른 장면으로 뽑아야 한다면? 클릭을 백 번 하긴 싫잖아요.

그래서 구조를 두 층으로 나눕니다.

클로드 코드가 "오늘 커피 광고를 장면만 바꿔서 다섯 개 만들어줘"라는 한 문단을 받으면, 1층의 CLI 명령을 장면만 갈아끼우며 다섯 번 알아서 돌립니다. 사람이 한 건 한국어 한 문단이 전부예요.

이 구조의 장점은 명확해요. "다섯 개"가 "오십 개"로 늘어나도 똑같이 돌아갑니다. 클릭 수십 번이 명령 한 줄로 압축되니까요.

3. 연동 3경로 — CLI vs MCP vs Skills

클로드 코드와 힉스필드를 붙이는 길은 세 가지예요. 헷갈리기 쉬우니 표로 정리하고 갈게요.

그래서 뭘 쓰면 되냐고요? 원칙은 이래요. 한 번에 여러 개를 줄줄이 돌리는 배치 작업엔 가벼운 CLI를 클로드가 부리는 쪽이 가뿐합니다. 무거운 웹 화면이나 도구 연동을 거치는 것보다, 셸 명령 한 줄을 반복하는 게 빠르고 단순하거든요.

⚠️ "MCP가 CLI보다 토큰을 35배 적게 쓴다, 신뢰도가 72%다" 같은 수치가 돌아다니는데, 출처가 한 군데(MindStudio)뿐이라 사실로 못 박진 않을게요. 정성적 원칙(배치엔 CLI가 유리)만 기억하시면 됩니다.

이 글은 CLI 경로를 기준으로 갑니다. 가장 가볍고, 클로드 코드로 자동화하기 좋으니까요. Skills와 MCP는 위 명령어로 언제든 추가할 수 있다는 것만 알아두세요. (MCP 명령의 --scope user는 "이 컴퓨터 어느 폴더에서든 쓰겠다"는 뜻이에요. 빼면 지금 폴더에만 등록돼서 "다른 데선 왜 안 되지?" 하게 됩니다.)

4. 5분 셋업 — 따라하기

준비물 3가지

1. Node.js 18 버전 이상 — nodejs.org에서 LTS라고 적힌 걸 설치하세요. 이게 없으면 다음 단계가 안 돌아가요.
2. 힉스필드 계정 + 크레딧 — 가입만 해두면 되는데, 크레딧이 0이면 영상이 안 만들어지니 최소 한 번은 충전해 두세요.
3. 터미널 — 맥은 '터미널', 윈도우는 'PowerShell'을 열면 됩니다.

4-1. 설치 — 공식 vs 비공식부터 구분

검색하면 비슷한 이름이 두 개 나와요. 여기서 한 번 헷갈리고 넘어가는 분이 많습니다.

파이썬 쓰시는 분들이 흔히 pip로 higgsfield-cli를 설치하시는데, 그건 공식이 아니에요. 우리가 쓸 건 npm으로 까는 @higgsfield/cli, 이거 하나만 기억하세요.

먼저 Node가 깔려 있는지 확인합니다.

node --version

v20.x.x 같은 버전이 찍히면 통과예요. command not found: node가 뜨면 Node가 아직 없는 거니, 위 준비물로 돌아가서 설치하고 오세요.

이제 설치 한 줄 갑니다.

npm install -g @higgsfield/cli

-g는 '글로벌', 컴퓨터 어디서든 부를 수 있게 깐다는 뜻이에요. 다 설치되면 실행 파일 이름은 higgsfield 입니다. 패키지 이름(@higgsfield/cli)이랑 부르는 명령(higgsfield)이 다른 게 포인트죠.

맥 사용자는 brew로도 설치할 수 있어요.

brew install higgsfield-ai/tap/higgsfield

brew로 깔아도 실행엔 Node 18 이상이 필요할 수 있으니, node --version 통과는 건너뛰지 마세요.

잘 들어갔는지 확인합니다.

higgsfield version

버전 번호가 찍히면 성공이에요. (혹시 command not found: higgsfield가 뜨면 PATH 문제니까, 아래 6장의 함정 섹션을 보세요.)

4-2. 인증 — API 키가 아니라 브라우저 로그인

여기서 많이들 막혀요. 이유는 'API 키를 어디다 붙여넣지?' 하고 키를 찾아 헤매기 때문이에요. 아닙니다.

higgsfield auth login

이 한 줄을 치면 브라우저가 알아서 열립니다. 거기서 힉스필드 계정으로 로그인하고 "허용"을 누르면 끝이에요. 토큰이 자동으로 받아져 로컬에 저장됩니다. 키 복사·붙여넣기, 그런 거 없어요.

참고로 "환경변수에 API 키를 넣는다"는 방식이 떠도는데, 공식 CLI 문서엔 그게 안 나와 있어요. 브라우저 로그인이 공식이고, API 키는 힉스필드의 별개 제품(Cloud API)일 수 있습니다. 우린 auth login 한 길로만 가죠.

4-3. 크레딧부터 확인하기

로그인됐으면 제일 먼저 잔액부터 봅니다.

higgsfield account

크레딧 잔액과 거래 내역이 나와요. 그리고 꼭 알아두실 게 하나 있어요.

⚠️ 웹사이트에서 무제한(Unlimited) 플랜을 쓰셔도, CLI에서는 적용이 안 됩니다. CLI로 만들면 항상 크레딧이 깎여요. 무제한은 웹 UI에서만이에요. 이거 모르고 막 돌리면 잔액이 훅 줄 수 있으니, 만들기 전에 account로 남은 크레딧을 확인하는 습관을 지금부터 들이세요.

4-4. 첫 영상 — hello-world

작업 폴더부터 하나 만들고 들어갑니다.

mkdir higgsfield-demo && cd higgsfield-demo

진짜로 만들기 전에, 얼마 깎이는지부터 봐요. 힉스필드엔 견적만 따로 보는 명령이 있거든요.

higgsfield generate cost kling3_0 --prompt "cinematic close-up of a matte black coffee bag on a wooden cafe counter, steam rising from a fresh cup, warm morning light, slow push-in"

화면에 나오는 숫자가 이번 작업에 깎일 크레딧이에요. 모델별 단가는 사람마다, 시점마다 달라요. 그러니 외운 숫자 믿지 말고 항상 cost로 직접 확인하세요. 화면에 찍힌 게 정답입니다.

견적 봤으면 진짜로 만듭니다.

higgsfield generate create kling3_0 --prompt "cinematic close-up of a matte black coffee bag on a wooden cafe counter, steam rising from a fresh cup, warm morning light, slow push-in" --duration 5 --mode pro --sound off --wait

옵션을 하나씩 볼게요.

• kling3_0 — 모델 이름이에요. 가성비가 좋아서 입문·데모용으로 무난하죠.
• --prompt — 만들 장면 설명.
• --duration 5 — 5초짜리.
• --mode — 품질·속도 모드. 모델마다 받는 값이 다르니 model get으로 확인하고 쓰세요.
• --sound off — 소리 빼기.
• --wait — 이게 핵심이에요. 다 만들어질 때까지 터미널이 기다려 줍니다. 안 붙이면 "접수했어요" 하고 바로 빠져나와요. 처음이니 기다리는 쪽으로 가죠.

폴링(상태 확인) 로그가 흐르다가 Completed가 뜨면서 결과 주소(URL)가 나와요. Queued나 Processing에서 멈춘 듯 보여도 정상이니 끄지 마세요. 주소가 나왔으면 파일로 받아옵니다.

curl -fsSL "<출력된 URL>" -o video.mp4

curl은 주소에서 파일을 내려받는 도구예요. -o video.mp4는 이 이름으로 저장하라는 거고요.

자동 저장해 주는 --download 같은 옵션은 쓰지 않습니다. 그건 다른 CLI(MiniMax mmx) 얘기라 여기선 안 먹어요. 저장은 curl로 직접 합니다.

이제 video.mp4를 더블클릭하거나 영상 플레이어로 열어보세요. (맥 터미널은 open video.mp4, 윈도우는 start video.mp4로도 열려요.) 짜잔 — 당신 터미널에서 영상 한 개가 나왔습니다.

보너스 — 핵심 명령 정리

화면 비율 함정 하나 — 가로 영상을 만들 때 비율 플래그는 이렇게 씁니다.

higgsfield generate create kling3_0 --prompt "..." --aspect_ratio 16:9 --resolution 2k --wait

--aspect_ratio, 가운데가 밑줄(_) 이에요. 점 두 개(하이픈) 아니고 밑줄. 습관적으로 --aspect-ratio로 쓰면 바로 에러가 납니다. (단, --start-image·--soul-id·--wait-timeout·--wait-interval은 하이픈이 맞아요.)

비동기 — 여러 개 동시에 — --wait를 빼면 기다리지 않고 작업 번호(job_id)만 툭 받고 다음으로 넘어가요. 영상 열 개를 한꺼번에 돌릴 때 결정적이죠. 폴링 간격은 기본 3초(--wait-interval), 최대 대기는 기본 10분(--wait-timeout)이고, 무거운 작업이면 timeout을 늘리면 됩니다.

5. ★ 실제 사례 — 사진 1장으로 QJC 홍보 광고를 진짜 만들었습니다

이게 이 글의 핵심 차별점이에요. "AI로 광고가 자동으로 된다"를 말이 아니라 실제 산출물로 증명했습니다. 정상록 대표 헤드샷 사진 딱 한 장으로 약 18초짜리 세로(9:16) 홍보 광고를 끝까지 만들었어요. 단계별로 그대로 재현 가능하게 풀어드릴게요.

5단계 워크플로우

STEP 1 — 키프레임 4씬 생성 (gpt-image-2, 얼굴 일관성 유지)

먼저 광고의 4개 장면을 정지 이미지로 만듭니다. 정상록 대표 사진을 레퍼런스로 넣어서, 4씬 모두 같은 얼굴이 나오게 했어요. 광고의 감정 곡선을 따라 4컷을 잡았습니다.

이미지 생성은 QJC 이미지 엔진(generate_image.py)을 경유하되, 레퍼런스 이미지(--ref)와 OpenAI 프로바이더(--provider openai)로 호출했습니다. 4씬 모두 동일 얼굴 일관성 검수를 통과시켰어요. (이 검수가 중요해요 — 광고는 같은 사람이 나와야 하니까요.)

STEP 2 — 각 키프레임을 영상으로 (Higgsfield image-to-video)

이제 정지 이미지를 움직이게 합니다. 핵심은 --start-image — 그 이미지를 첫 프레임으로 깔고 거기서부터 영상이 시작되게 하는 거예요. 각 씬의 움직임을 프롬프트로 적어줬습니다.

higgsfield generate create kling3_0 --start-image scene-1.png --prompt "exhausted man sighs at a desk piled with paperwork, late night, slow zoom in" --aspect_ratio 9:16 --duration 5 --sound off --wait --json

씬마다 --start-image(키프레임)와 --prompt(움직임 묘사: 한숨/타이핑/미소/끄덕임)만 바꿔 네 번 돌렸어요. 완료된 JSON 응답에서 mp4 URL을 뽑아 curl로 받았습니다.

curl -fsSL "<출력된 mp4 URL>" -o scene-1.mp4

--start-image에는 로컬 파일 경로(scene-1.png)를 바로 넣을 수 있어요. CLI가 자동으로 업로드해 줍니다. 같은 이미지를 여러 번 쓸 거면, higgsfield upload --image ./img.png --json으로 한 번 올려 받은 UUID를 재사용하는 게 더 빠르고요.

STEP 3 — ffmpeg로 합성 + 한글 자막 번인 + 전환

네 클립을 하나로 잇습니다. 1080×1920 세로로 맞추고, AppleSDGothicNeo 한글 폰트로 자막을 영상에 직접 새겨 넣고(번인), 클립 사이에 crossfade 전환(0.5초)을 줬어요. 자막은 각 씬의 메시지를 얹었습니다 — 실제로 쓴 4개 자막은 이거예요.

합성은 ffmpeg xfade(클립 간 crossfade) + drawtext(자막 번인)로 조립했어요. 명령이 길어 한 줄로 옮기진 않고, 전체 조립 스크립트는 build-promo.sh로 묶어뒀습니다 — 그대로 따라 하시려면 이 스크립트를 참고하세요. 골격만 보면 이런 모양이에요.

# 네 클립을 xfade로 잇고(crossfade 0.5s), 각 씬 자막을 drawtext로 번인
ffmpeg -i scene-1.mp4 -i scene-2.mp4 -i scene-3.mp4 -i scene-4.mp4 \
  -filter_complex "[0][1]xfade=transition=fade:duration=0.5:offset=4[a]; \
  [a][2]xfade=transition=fade:duration=0.5:offset=8[b]; \
  [b][3]xfade=transition=fade:duration=0.5:offset=12, \
  drawtext=fontfile=AppleSDGothicNeo.ttc:text='혼자 다 하느라 벅차시죠?':...[v]" \
  -map "[v]" promo.mp4

STEP 4 — BGM + 나레이션 믹싱

Suno로 BGM을 생성하고, ElevenLabs로 한국어 나레이션 4문장을 만들었어요. ffmpeg amix로 합치되, 음성(VO)을 1.5로 앞세우고 BGM은 0.28로 배경에 깔았습니다. 광고는 목소리가 들려야 하니까요.

비용 — 실측

흥미로운 건 가이드 예측(24~28크레딧)과 실측(25크레딧)이 정확히 맞았다는 거예요. generate cost로 사전 견적을 보고 들어가면 비용이 안 튄다는 뜻이죠.

CLI 실측으로 확인한 사실

이 광고를 만들면서 CLI 동작을 직접 검증했습니다.

• 설치: npm install -g @higgsfield/cli (버전 v0.1.40 확인)
• 인증: higgsfield auth login이 브라우저로 higgsfield.ai/device?code=... 승인 페이지를 열어요. 브라우저에서 직접 승인해야 하고, CLI가 이걸 대신 눌러줄 순 없습니다.
• 계정 상태: higgsfield account로 플랜(ultra)과 크레딧 잔액 확인.
• 이미지 입력: --start-image에 로컬 경로를 주면 자동 업로드.
• ⚠️ 크레딧: CLI는 항상 크레딧을 차감합니다. Unlimited 플랜이어도 CLI엔 적용 안 돼요.

이게 왜 의미 있나 — 2레이어의 실증

이 광고는 클로드 코드(두뇌)가 Higgsfield CLI(손발)를 오케스트레이션한 2레이어 구조의 실제 증명이에요. 사진 한 장 → 키프레임 4씬 → image-to-video 4클립 → 합성·자막·BGM·나레이션. 사람이 한 건 "이런 광고 만들어줘"라는 지시와 키프레임 얼굴 검수였고, 나머지 실행은 CLI가 했습니다.

말로 "자동화됩니다"가 아니라, 실제로 약 18초 광고가 폴더에 떨어졌다 — 이게 차이예요.

6. 비용과 함정 — 미리 알면 안 당합니다

모델별 정확한 크레딧 단가도 공식 문서에 박혀 있지 않아요. "모델·해상도·배치 크기에 비례한다"는 사실만 확실하고, 정확한 숫자는 generate cost로 실측이 정답입니다.

7. 오늘 시작하기 — 가장 작은 첫걸음

거창하게 시작하지 마세요. 오늘 당장 할 수 있는 가장 작은 한 걸음은 이거예요.

내 제품 사진 딱 한 장으로, 광고 클립 하나 만들어보기.

# 1) 설치
npm install -g @higgsfield/cli
# 2) 로그인 (브라우저 열림)
higgsfield auth login
# 3) 잔액 확인
higgsfield account
# 4) 사진 1장 → 영상
higgsfield generate create kling3_0 --start-image ./my-product.jpg --prompt "the product on a clean counter, slow cinematic dolly-in, warm light" --aspect_ratio 9:16 --duration 5 --sound off --wait --json
# 5) 결과 URL을 curl로 저장
curl -fsSL "<출력된 URL>" -o ad.mp4

이거 하나가 되면, 나머지는 전부 응용이에요. 제품 100개로 늘리면 광고 카탈로그가 되고, 클로드 코드를 얹으면 "이 폴더 전부 광고로 만들어줘" 한 마디로 끝나죠.

그런데 — 양산이 목적이면 슬롭(쓰레기 양산)입니다

솔직하게 짚을게요. AI 영상은 아직 손이나 글자가 깨질 때가 있고, 디테일이 어색할 때도 있어요. 다 되는 건 아니에요.

그래서 저는 이렇게 씁니다. 자동화로 시안을 잔뜩 뽑고, 사람이 그중 쓸 만한 걸 고른다. 양산이 목적이 아니라 '고를 시간'을 버는 거예요. 그게 슬롭(저자 없는 평균값)과 진짜의 차이입니다.

AI = 시안 양산 → 사람이 큐레이션  ✅
양산 자체가 목적                  ❌ (슬롭)

맺음

정리하면 이렇습니다. 터미널 한 줄이 영상 한 개, 클로드 코드가 그걸 수십 개로. 이 2레이어 구조 하나만 손에 익히면, 다음에 만들 것도 전부 같은 원리예요.

저희는 이걸 말로만 한 게 아니라, 사진 한 장으로 진짜 광고를 만들어 증명했습니다. 당신도 오늘 제품 사진 한 장으로 시작해보세요.

• 더 많은 시스템 자동화 이야기 → https://qjc.app
• QJC 채널 → https://www.youtube.com/@qjc_qjc
• 영상으로 보고 싶다면 → https://www.youtube.com/@qjc_qjc

만들고 싶은 광고가 있다면, 어떤 장면인지 한 줄로 적어 보내주세요. 다음 편에서 직접 돌려보겠습니다. — 시스템 만드는 남자, QJC

📝 이 가이드 전문(복붙용 명령어 포함) → GitHub Gist

면책: 본 가이드의 명령어는 2026-06-04 기준 공식 GitHub README/MODELS.md로 검증된 항목만 코드블록에 담았습니다. CLI는 v0.1.x 프리-1.0이라 명령어가 바뀔 수 있으니, 안 되면 --help 또는 model list로 현재 사양을 확인하세요. 모델별 크레딧 단가는 generate cost로 실측하시기 바랍니다.