Vercel ai-cli는 이미지·영상·음성·텍스트 생성 모델을 터미널 명령 하나로 부르고, 같은 기능을 MCP 서버로 Claude Code·Codex·opencode에 붙이게 해 주는 도구입니다. 모든 호출이 Vercel AI Gateway를 거치므로 비용과 데이터 보관 조건은 Gateway 정책이 정하고, 기본 이미지·영상 모델은 무보관(ZDR) 대상이 아니라는 점을 알고 써야 합니다.
코딩 에이전트에게 “썸네일 하나 만들어 줘”, “이 화면을 5초 영상으로 바꿔 줘”를 맡기려면 지금까지는 모델사마다 API 키를 받고, 각자의 MCP 서버나 스크립트를 따로 붙여야 했습니다. Vercel Labs가 공개한 ai-cli(npm i -g ai-cli, 실행 명령은 ai)는 이 연결을 Vercel AI Gateway 키 하나로 묶습니다. 저장소 설명은 “Generate anything from your terminal”이고, 2026년 11월 4일 기준 최신 버전은 0.9.0입니다.
README, 공식 문서, npm 기록, AI Gateway 문서를 직접 확인해 구조와 비용, 데이터 정책, 한계를 정리합니다.
기본 사양과 등장 경위
| 항목 | 내용 |
|---|---|
| 성격 | Vercel Labs 실험 프로젝트(README의 “LABS EXPERIMENT” 배지) |
| 최신 버전 | 0.9.0(2026-11-04), npm 패키지명 ai-cli |
| 라이선스 | Apache-2.0(npm·package.json 표기) |
| 요구 사항 | Node.js 22 이상, AI Gateway API 키 |
| 기반 | Vercel AI SDK(ai 7.0.139), @ai-sdk/gateway 4.0.112 |
| 지표 | GitHub 스타 903, 포크 약 70, npm 주간 다운로드 2,309회(10월 28일~11월 3일) |
저장소는 2025년 7월 28일에 만들어졌지만, 지금의 도구와 그때의 도구는 다릅니다. npm 기록을 보면 2025년 8월의 0.0.1은 “OpenAI 오픈소스 모델을 쓰는 AI CLI”, 2026년 3월의 0.0.13은 “작은 터미널 AI 비서”였습니다. 2026년 5월 1일 0.1.0에서 변경 기록이 “새 ai-cli의 첫 출시”라고 적으며 이미지·영상·텍스트 생성 도구로 바뀌었습니다.
이후 Vercel CEO 기예르모 라우치가 5월 14일 X에 터미널에서 이미지를 만드는 예시를 올렸고, 10월 8일 Vercel의 FLUX 3 Image 출시 공지(changelog)도 터미널 사용법으로 AI CLI를 안내했습니다. 최근 주목도와 직접 이어지는 변화는 두 가지입니다. 10월 29일 0.8.0에서 MCP 서버(ai mcp)가 추가됐고, 11월 4일 0.9.0에서 키를 한 번 저장해 두는 ai login이 생겼습니다. ai-cli만 다룬 Vercel 블로그 발표문은 찾지 못했습니다.
명령 구성과 지원 모델
명령은 생성 대상별로 나뉩니다. README가 보여 주는 기본 사용법은 다음과 같습니다.
ai image "a cute dog"
ai video "a spinning triangle"
ai text "explain quantum computing"
ai audio speak "Thanks for trying ai-cli"
ai audio transcribe recording.mp3
ai decide --boolean "refund=Refund requested?" < ticket.txt
ai models # list available models
ai mcp --profile all # start MCP server명령끼리 파이프로 이어지고, 쉼표로 여러 모델을 한 번에 비교할 수 있습니다.
ai image "a dragon" | ai video "animate this"
ai image "a sunset" -m "openai/gpt-image-1,xai/grok-imagine-image,bfl/flux-2-pro"모델 목록은 CLI 안에 고정돼 있지 않고 AI Gateway에서 실시간으로 받아 옵니다. 11월 4일 Gateway 공개 모델 목록을 직접 조회한 결과는 아래와 같습니다.
| 분야 | Gateway 모델 수 | ai-cli 기본 모델 | 주요 제공사 |
|---|---|---|---|
| 이미지 | 37개(+이미지 생성 가능한 언어 모델 8개) | openai/gpt-image-2 | OpenAI, Black Forest Labs, ByteDance, Recraft, Google Gemini 이미지 |
| 영상 | 39개 | bytedance/seedance-2.0 | ByteDance, Google Veo, Kling, Alibaba Wan, MiniMax |
| 음성 합성 | 24개 | openai/tts-1 | ElevenLabs, Fish Audio, OpenAI, Google |
| 받아쓰기 | 16개 | openai/whisper-1 | OpenAI, ElevenLabs, Mistral |
| 판정(decide) | 14개 | typesafe-ai/jev | TypeSafe AI, Perplexity, Baseten |
ai decide는 입력을 보고 예/아니오 확률, 선택지, 점수를 JSON으로 돌려주는 판정 명령입니다.
MCP로 코딩 에이전트에 붙이기
ai mcp는 표준 입출력(stdio)으로 도는 로컬 MCP 서버입니다. 공식 문서가 안내하는 Claude Code와 Codex 연결 명령은 다음과 같습니다.
claude mcp add ai -e AI_GATEWAY_API_KEY=your-vercel-ai-gateway-api-key -e AI_CLI_OUTPUT_DIR=/absolute/output/dir -- ai mcp
codex mcp add ai --env AI_GATEWAY_API_KEY=your-vercel-ai-gateway-api-key --env AI_CLI_OUTPUT_DIR=/absolute/output/dir -- ai mcp기본 프로필(core)은 text, image, decide, models 네 개 도구만 엽니다. 영상(video_start, video_status)과 음성(audio_speak, audio_transcribe)을 쓰려면 --profile media나 --profile all을 붙여야 합니다. 영상 도구는 작업을 걸어 두고 나중에 상태를 확인하는 비동기 방식입니다.
키는 서버 환경 변수로만 받으므로 에이전트가 읽을 수 없고, Gateway 주소나 팀을 바꾸는 플래그는 거부해 키가 다른 서버로 새지 않게 막습니다.
비용과 데이터 정책
ai-cli 자체는 무료이고 과금은 AI Gateway에서 일어납니다. Vercel 공식 문서 기준 구조는 이렇습니다.
- 수수료 없음: Gateway는 토큰에 마크업이나 플랫폼 수수료를 붙이지 않고 제공사 정가로 청구합니다. 결제 처리 수수료는 이용자 부담입니다.
- 무료·유료 구간: 무료 크레딧은 일부 모델만 쓸 수 있고 모델별 호출 한도가 낮습니다. 크레딧을 사면 유료 구간으로 바뀌고 월 무료 크레딧은 더 주지 않습니다.
- BYOK: 자기 제공사 키를 등록하는 방식(Bring Your Own Key)도 추가 수수료가 없지만 크레딧을 산 유료 구간에서만 됩니다. 내 키로 실패하면 Vercel 키로 다시 시도하고 그 비용은 크레딧에서 빠집니다. BYOK 지출은 Gateway 예산 한도에 잡히지 않습니다.
“데이터 보관 정책 관리”는 Gateway의 무보관(Zero Data Retention, ZDR) 기능을 가리킵니다. 문서에 따르면 Vercel은 프롬프트와 출력을 보관하지 않고, 요청이 끝나면 바로 지웁니다. 제공사 쪽 보관까지 막으려면 요청마다 zeroDataRetention: true를 켜거나(추가 비용 없음) 팀 전체에 켜야 합니다(성공 요청 1,000건당 0.10달러). 두 방식 모두 유료 계정에서만 되고 무료 크레딧으로는 쓸 수 없습니다.
문제는 생성 모델입니다. Gateway 모델 목록에서 ZDR이 되는 이미지 모델은 37개 중 5개, 영상은 39개 중 15개(Google Veo, Alibaba Wan 계열)입니다. ai-cli의 기본 모델인 gpt-image-2와 seedance-2.0은 둘 다 ZDR 대상이 아닙니다. ai-cli에는 ZDR 전용 옵션이 없습니다. 이미지·영상·decide 명령의 --provider-options JSON이 Gateway 설정을 그대로 넘기지만, 이 경로로 ZDR을 켜는 방법은 공식 문서에 나오지 않습니다.
한계·주의점
- 1.0 이전 실험작입니다. 0.6.0에서 이미지·영상 플래그 이름과 JSON 출력 형식이 크게 바뀌었습니다. 스크립트에 넣을 때는 버전을 고정하는 편이 안전합니다.
- README 예시와 실제 모델 이름이 다를 수 있습니다. README의
xai/grok-imagine-image는 11월 4일 Gateway 목록에서spacexai/grok-imagine-image로 나옵니다. 쓰기 전에ai models로 확인해야 합니다. - MCP 도구 시간 제한: 문서는 opencode가 도구 호출을 30초에 끊으므로 timeout을 늘리라고 안내합니다. 영상 작업 파일에는 웹훅 서명 비밀값이 들어갈 수 있어 외부에 공유하면 안 됩니다.
- 저장소에 LICENSE 파일이 없습니다. 라이선스는 npm·package.json의 Apache-2.0 표기로만 확인됩니다.
어디에 쓰면 맞는가
| 방식 | 연결·인증 | 과금 |
|---|---|---|
| ai-cli + AI Gateway | 로컬 stdio MCP와 CLI, Gateway 키 하나 | Gateway 크레딧, 제공사 정가 |
| 모델사 API·MCP 직접 연결 | 제공사마다 키와 설정 따로 | 제공사별 청구 |
| Replicate MCP | npm replicate-mcp 또는 원격 서버, Replicate API 키 |
Replicate 계정 |
| fal MCP | 원격 서버(Streamable HTTP), 브라우저 OAuth 로그인 | fal 크레딧 |
ai-cli가 맞는 곳은 셸 스크립트와 코딩 에이전트에서 여러 회사의 이미지·영상·음성 모델을 번갈아 써야 하는 팀입니다. 키와 청구서가 하나로 모이고, 결과가 파일과 JSON으로 떨어져 자동화에 붙이기 쉽습니다. 반대로 한 제공사 모델만 쓰거나, 고객 자료처럼 민감한 이미지를 다루면서 기본 모델을 그대로 쓰려는 경우라면 무보관 조건부터 따져 봐야 합니다.
자주 묻는 질문
Q. OpenAI나 Google 키가 따로 있어야 하나요?
A. 아닙니다. AI Gateway API 키 하나면 됩니다. 원하면 자기 제공사 키를 Gateway에 등록하는 BYOK도 쓸 수 있지만, 크레딧을 산 유료 구간에서만 됩니다.
Q. Claude Code에서 영상까지 만들 수 있나요?
A. 됩니다. 다만 MCP 서버를 --profile media 또는 --profile all로 띄워야 영상·음성 도구가 열립니다. 기본 프로필은 텍스트·이미지·판정·모델 조회만 엽니다.
Q. 입력한 프롬프트와 이미지는 어디에 남나요?
A. Vercel은 보관하지 않는다고 밝혔습니다. 제공사 쪽 보관 여부는 모델마다 다르고, 무보관을 강제하려면 유료 계정에서 ZDR을 켜고 ZDR이 되는 모델을 골라야 합니다.
출처: vercel-labs/ai-cli GitHub 저장소(README, CHANGELOG, package.json), ai-cli 공식 문서(MCP), npm ai-cli, Vercel AI Gateway 가격 문서, BYOK 문서, ZDR 문서, Vercel changelog (2026-10-08), 기예르모 라우치 X 게시물 (2026-05-14), Replicate MCP 문서, fal MCP 문서
대표 이미지: ai-cli 공식 사이트(ai-cli.dev) 소셜 공유 이미지(흑백 변환)
