Claude Code와 eroq CLI: 코딩 에이전트로 에셋 생성하기

코딩 에이전트는 랜딩 페이지의 거의 모든 걸 잘 만들어요. 히어로 이미지만 빼고요. <picture> 태그는 쓸 수 있어도 그림 자체는 만들지 못하죠. 미디어 API는 URL이나 base64 덩어리를 돌려주는데, 에이전트가 정말 원하는 건 다음 편집에서 참조할 수 있는 경로에 놓인 파일이에요. eroq CLI가 그 간극을 메워요. eroq mcp는 stdio로 로컬 MCP 서버를 실행하고, 이 서버의 도구들은 렌더를 프로젝트 안에 파일로 저장한 뒤 경로를 돌려줘요.

저희가 직접 쓰는 워크플로예요. 명령어와 환경 변수, 그리고 마지막에 전체 세션까지 담았어요.

설치와 로그인

패키지는 npm에 있고, Node 18 이상이 필요하며, 의존성이 하나도 없어요.

npm install -g @eroq/cli
eroq login          # paste a key from the developers dashboard
eroq account        # balance, plan, workspace

eroq login은 키를 ~/.config/eroq/config.json에 0600 권한으로 저장해요. 환경 변수 두 개가 이 값을 덮어쓰는데, CI나 에이전트 설정에서는 바로 이 방식이 필요해요.

• EROQ_API_KEY — 키. 저장된 키보다 우선해요.
• EROQ_API_URL — 기본 URL로, 기본값은 https://eroq.ai예요. 스테이징 배포를 가리키는 게 아니라면 건드리지 마세요.

명령어

모든 명령어는 저장한 내용과 사용량 한 줄("Spent 100 credits · 887 remaining")을 출력해요.

eroq models                                     # models, credit prices, plan gates
eroq voices                                     # roster + your clones
eroq enhance "kettle on a counter" --kind image # free prompt rewrite
eroq image "…" -m eroq-image-one -o public/img/hero.webp
eroq video "…" -s 10 --aspect 9:16 --shot push-in -o public/video/teaser.mp4
eroq speech "…" -v orion --speed 0.95 -o public/audio/intro.mp3

알아 두면 좋은 플래그예요. -m은 모델을 고르고(이미지는 기본 eroq-image-one, 동영상은 eroq-motion-one), -s는 클립 길이(초)예요. 상한은 플랜이 정하고 값은 엔진이 지원하는 길이에 맞춰 조정돼요(동영상 문서 참고). --aspect는 16:9, 9:16, 1:1 중 하나, --shot은 카메라 무빙 중 하나, --ref는 사진 URL(클립에는 이미지 투 비디오 소스, 정지 이미지에는 유지할 얼굴), --negative는 네거티브 프롬프트, -o는 출력 경로예요. -o가 없으면 ./eroq-image-<timestamp>.webp, ./eroq-video-<timestamp>.mp4, ./eroq-speech-<timestamp>.mp3로 저장돼요.

Claude Code에 연결하는 두 가지 방법

서버는 두 가지이고, 둘 사이에는 중요한 차이가 하나 있어요.

원격, HTTP 방식. Claude Code가 https://eroq.ai/mcp와 직접 통신해요. 도구는 URL을 반환하고, generate_video는 렌더가 아직 끝나지 않았으면 작업 id를 반환해요.

claude mcp add --transport http eroq https://eroq.ai/mcp \
  --header "Authorization: Bearer eroq_sk_YOUR_KEY"

로컬, stdio 방식. Claude Code가 eroq mcp를 자식 프로세스로 실행해요. 도구는 작업 디렉터리에 파일을 저장하고 경로를 반환하며, generate_video는 렌더가 끝날 때까지(최대 8분) 기다리기 때문에 에이전트는 영수증이 아니라 MP4를 받아요.

claude mcp add eroq --env EROQ_API_KEY=eroq_sk_YOUR_KEY -- npx -y @eroq/cli mcp

코딩 작업에는 로컬 방식을 쓰세요. eroq install claude-code를 실행하면 저장된 키가 미리 들어간 두 스니펫을 모두 출력해요. 로컬 도구는 generate_image, generate_video, generate_speech, enhance_prompt, list_models, list_voices, list_characters, get_account이고, 앞의 세 개는 out_path를 받아요.

Cursor는 ~/.cursor/mcp.json(프로젝트에서는 .cursor/mcp.json)을 읽어요.

{
  "mcpServers": {
    "eroq": {
      "url": "https://eroq.ai/mcp",
      "headers": { "Authorization": "Bearer eroq_sk_YOUR_KEY" }
    }
  }
}

Codex CLI는 ~/.codex/config.toml을 읽고 stdio 서버를 실행해요.

[mcp_servers.eroq]
command = "npx"
args = ["-y", "@eroq/cli", "mcp"]
env = { EROQ_API_KEY = "eroq_sk_YOUR_KEY" }

eroq install cursor와 eroq install codex도 이 설정을 출력해요. 전체 연결 방법은 MCP 문서에 정리돼 있어요.

실전 세션: 랜딩 페이지용 에셋

과제는 가상의 푸어오버 주전자를 위한 랜딩 페이지예요(제품 동영상의 대표적인 사례죠). 에이전트에게는 로컬 서버, public/ 폴더, 그리고 약 250 크레딧의 예산이 있어요. 아래는 살짝 다듬은 실행 기록이에요.

Agent: Checking the wallet before I spend anything.
       [get_account] → 1,000 credits, no plan (clips capped at 10 s)

Agent: Tightening the hero prompt first — it's free.
       [enhance_prompt kind=image prompt="black kettle, morning light, premium"]
       → "Close-up of a matte black pour-over kettle on a walnut counter, steam
          curling up into morning window light, shallow depth of field, soft cross
          lighting, a few coffee beans scattered out of focus, calm and premium,
          product photography, warm film palette."

Agent: [generate_image model=eroq-image-one out_path=public/img/hero.webp]
       → Image saved to public/img/hero.webp · Spent 10 credits · 990 remaining

Agent: Two feature tiles on the same look, then a vertical teaser.
       [generate_image … out_path=public/img/feature-pour.webp]   → 10 credits
       [generate_image … out_path=public/img/feature-temp.webp]   → 10 credits
       [generate_video model=eroq-motion-one seconds=10 aspect=9:16
        out_path=public/video/teaser.mp4
        prompt="Slow push-in on the same matte black kettle as steam rises and
        drifts toward the window, morning light warming from blue to gold, tiny
        dust motes in the beam, shallow focus holding on the spout, calm premium
        mood, 35mm film look."]
       → Clip saved to public/video/teaser.mp4 · Spent 60 credits · 910 remaining

Agent: A scratch voice-over for the hero, Orion, a touch slower.
       [generate_speech voice=orion speed=0.95 out_path=public/audio/intro.mp3
        text="Pour slower. Taste more. The kettle that waits for you."]
       → Speech saved to public/audio/intro.mp3 · Spent 3 credits · 907 remaining

Agent: Wiring them into index.html now.

그다음 에이전트가 마크업을 써요. <img src="/img/hero.webp">, 티저를 담은 음소거 자동 재생 <video>, 재생 버튼 뒤에 둔 <audio> 요소까지 넣으면 페이지가 실제로 완성돼요. 합계는 93 크레딧으로, 입문 팩 요율로 치면 약 $2예요. 사람보다 테이크를 적게 렌더한다는 게 여기서 에이전트의 유일한 장점이에요. 세 번째 변형에 반해 버리는 일이 없거든요.

이 방식을 안정적으로 만드는 습관이 두 가지 있어요. 먼저 에이전트에게 get_account부터 호출하라고 하세요. 그래야 시작하기 전에 플랜의 클립 상한과 잔액을 알 수 있어요. 그리고 항상 out_path를 넘기세요. 프로젝트 루트에 타임스탬프 이름으로 저장되는 기본값은 빠른 테스트에는 괜찮지만, 저장소에서는 엉망이 돼요.

돈을 쓸 수 있는 에이전트를 위한 안전장치

• 전용 키. 에이전트용 키를 따로 만들어 자체 요청 한도를 주고, 프로젝트가 끝나면 폐기하세요.
• git에 넣지 마세요. Claude Code의 --env와 Codex의 TOML은 저장소 밖에 있어요. 키가 들어간 프로젝트 단위 .cursor/mcp.json은 .gitignore에 넣어야 해요.
• 실패는 무료예요. 실패한 렌더는 자동으로 환불되고, 정책을 벗어난 프롬프트는 content_blocked를 반환하며 절대 과금되지 않아요. 에이전트에게는 "한 번 더 시도하고, 그래도 안 되면 물어보기" 이상의 재시도 로직이 필요 없어요.
• 모델 제한은 명확해요. 프리미엄 동영상 엔진에는 플랜이 필요하고, 잠긴 모델은 과금 전에 403 plan_required로 응답해요. 내 키로 쓸 수 있는 모델은 eroq models로 확인하세요.

자주 묻는 질문

원격 MCP 서버를 이미 쓰고 있다면 CLI가 필요한가요?

아니요. 원격 서버는 헤더를 보낼 수 있는 모든 클라이언트에서 작동해요. CLI의 stdio 서버는 URL 대신 디스크의 파일을 원하는 에이전트를 위한 거예요.

CLI로 어떤 모델을 쓸 수 있나요?

플랜이 여는 모든 모델이요. 이미지 모델 세 개, eroq models에 나오는 동영상 엔진, 음성 모델 두 개와 음성 목록, 그리고 내 복제 음성과 캐릭터까지요.

에이전트가 내 캐릭터를 쓸 수 있나요?

네. list_characters는 내 캐스트를 반환해요. generate_speech에 char:<id>를 넘기면 그 캐릭터의 목소리로 말하고, --ref에 캐릭터 사진을 넘기면 여러 이미지에 걸쳐 얼굴을 유지하거나 이미지 투 비디오의 소스로 쓰여요.

준비됐나요? API 키를 받고 eroq login을 실행한 다음, 지루한 일은 에이전트에게 맡기세요.