Sume CLI로 터미널에서 아바타 영상 생성하기

Sume CLI(sume)는 api.sume.com/v1 Developer API를 감싸는 에이전트 우선(agent-first) 명령줄 래퍼입니다. 터미널에서 Avatar 1.0과 Avatar Video 1.0으로 아바타와 말하는 아바타 영상을 만들고, 그 결과로 생긴 Job을 지켜보고, 가져오고, 내려받습니다. Image 1.0, Video 1.0, Music 1.0은 현재 CLI 서브커맨드가 없습니다. 이 계열은 API로 제출하세요. 그래도 Job은 CLI로 복구할 수 있습니다.

아래 명령어와 플래그는 CLI 개요와 그 하위 페이지인 설치, 인증, 생성, Job, agent skills, 보안 페이지를 바탕으로 합니다.

Sume CLI는 어떻게 설치하나요?

권장 경로는 호스팅 인스톨러이며, 명령어는 아래와 같습니다. 인스톨러가 하는 일과 업데이트 방법은 다음과 같습니다.

• 최신 sumelabs/cli GitHub Release를 확인하고, OS와 아키텍처에 맞는 바이너리를 내려받습니다.
• checksums.txt로 바이너리를 검증합니다.
• ~/.sume-com/bin 아래에 sume를 설치하며, PATH에 이미 있는 다른 sume를 조용히 덮어쓰지 않습니다.
• sume update --check는 로컬 파일을 바꾸지 않고 더 새로운 GitHub Release가 있는지 알려 줍니다. 업그레이드하기로 했다면 호스팅 인스톨러를 다시 실행하세요.

# macOS or Linux
curl https://cli.sume.com/install -fsS | bash

# Windows PowerShell
irm https://cli.sume.com/install.ps1 | iex

# Verify
sume version
sume doctor --agent --json
sume update --check

로그인은 어떻게 하나요?

sume login을 실행한 뒤 sume auth status를 실행하세요. CLI가 user_code와 함께 www.sume.com/cli/login 기기 승인 페이지를 열고, 승인을 기다린 뒤 CLI 범위의 API 키를 로컬 설정에 저장합니다. 기본 위치는 ~/.sume-com/config.json입니다. 원격 머신이나 헤드리스 머신에서는 sume login --no-browser가 브라우저를 여는 대신 승인 URL을 출력합니다.

CI와 서버 자동화에서는 sume auth setup --api-key "$SUME_API_KEY"로 키를 직접 설정하거나, SUME_API_KEY, SUME_API_BASE_URL, SUME_API_AUTH_MODE 환경 변수를 쓰세요. CLI는 기본으로 x-api-key를 보내며, SUME_API_AUTH_MODE=bearer로 설정하면 Authorization: Bearer로 바뀝니다. 수동 키는 API Keys 대시보드에서 발급하고, 스코프와 키 교체는 Sume API 키의 동작 방식에서 다룹니다.

CLI에는 어떤 생성 명령어가 있나요?

생성 기능은 Avatar 중심입니다. 두 계열에는 일급 제출 명령어가 있고, 나머지는 API 우선입니다. 문서는 이 계열의 CLI 명령어를 지어내지 말라고 안내합니다.

호스팅 MCP 서버는 별도의 표면이며, 여기에는 generate_image, generate_video, music_create 도구가 있습니다. Claude Code, Cursor, Codex에 연결하는 방법을 참고하세요.

터미널에서 말하는 아바타 영상은 어떻게 만드나요?

sume avatars list --agent --json으로 아바타 핸들을 확인한 뒤, 아래 예시처럼 sume avatar-videos create로 제출하세요. 같은 요청의 API 버전은 스크립트로 말하는 아바타 영상 만들기에 있습니다.

• 이 명령어는 크레딧을 예약하거나 쓸 수 있으므로 --confirm-paid가 필요합니다.
• 스크립트의 예상 길이는 4-60초(양 끝 포함)여야 합니다. CLI가 제출 전에 이를 검증합니다.
• --quality는 standard, plus, max를 받고, 기본값은 공개 API와 같은 plus입니다. 문서는 속도가 중요하면 standard를, 처리 시간보다 품질이 중요하면 max를 권합니다.
• 새 아바타를 만들 때 sume avatars create는 --type prompt, --type photo, --type props를 받습니다. --payload-json이나 --payload-file로 요청 본문을 그대로 보낼 수 있습니다.

sume avatar-videos create \
  --confirm-paid \
  --avatar-handle product_host \
  --product-image https://example.com/product.png \
  --script "Say hello to the Sume developer platform." \
  --quality plus \
  --json

완성된 영상은 어떻게 받나요?

모든 제출 명령어는 Job ID를 반환하거나 출력합니다. 프로세스가 재시작되거나 로컬 타임아웃이 발생하면 유료 작업을 다시 제출하지 말고 아래 명령어로 Job을 복구하세요.

• sume jobs watch는 Job이 종료 상태가 되거나 대기 시간이 끝날 때까지 폴링합니다.
• sume jobs download는 완료된 미디어 산출물을 로컬 디렉터리에 저장합니다.
• sume jobs cancel <job_id> --confirm-submit은 Job을 취소합니다.
• API로 만든 Image, Video, Music Job에도 같은 Job 명령어가 동작합니다.

sume jobs status <job_id> --agent --json
sume jobs events <job_id> --agent --json
sume jobs result <job_id> --agent --json
sume jobs watch <job_id>
sume jobs download <job_id> --output-dir ./out

코딩 에이전트가 Sume CLI를 안전하게 실행할 수 있나요?

CLI는 에이전트가 쓰도록 설계됐습니다. 문서는 다음 한 가지 루프를 권장합니다. 카탈로그와 로컬 준비 상태를 확인하고, sume tools schema avatar-videos.create --json 같은 읽기 전용 스키마 명령어로 페이로드를 검증하고, 쓰기나 유료 작업 전에는 확인을 요청하고, 범위가 제한된 Job 하나를 제출하고, Job 명령어로 복구하고, 비밀 값이나 서명된 URL을 붙여 넣지 않고 결과를 요약합니다.

• --confirm-submit은 Job 취소나 에셋 등록처럼 유료가 아닌 쓰기에 거는 게이트입니다. --confirm-paid는 Avatar와 Avatar Video 생성에 거는 게이트입니다.
• --json은 기계가 읽을 수 있는 안정적인 출력을 줍니다. --agent --json은 지원되는 곳에서 URL 형태의 필드와 계정·워크스페이스 정보를 가리거나 요약하는 일까지 합니다.
• sume skills install은 번들 Sume skill을 .agents/skills 또는 .claude/skills에 씁니다. sume skills export sume로 파일을 먼저 검토할 수 있습니다.
• SUME_API_KEY, ~/.sume-com/config.json, 원본 프로바이더 페이로드는 절대 출력하거나 커밋하지 마세요. 결과 미디어 URL은 공개 URL이지만 여전히 사용자 데이터입니다.