문제 해결

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

읽기 전용 점검부터 시작하세요.

API 키가 없을 때

브라우저 로그인부터 시작하세요.

원격이나 헤드리스 터미널에서는 다음을 사용합니다.

CI와 서버 자동화를 위한 수동 API 키 설정과 환경 변수도 사용할 수 있습니다.

API 베이스가 잘못됐을 때

로컬 설정을 확인하세요.

현재 프로덕션 API 베이스는 다음과 같습니다.

Job은 생성됐는데 결과가 아직 없을 때

Job은 비동기입니다. 상태를 폴링하세요.

결과는 완료된 뒤에만 가져오세요.

로컬 대기가 타임아웃됐다면 다른 유료 Job을 제출하기 전에 기존 Job을 먼저 확인하세요.

Image / Video / Music CLI 명령어가 없을 때

출시된 CLI에는 sume image, sume video, sume music 서브커맨드가 없습니다. 이 계열들은 Developer API(Image, Video, Music)로 제출한 다음 sume jobs status / sume jobs result로 복구하세요.

로컬 MCP가 실행되지 않을 때

현재 릴리스는 coming_soon을 보고합니다. Cursor/Claude에서는 https://mcp.sume.com/mcp의 호스팅 MCP를 사용하거나 CLI 명령어를 직접 실행하세요.

미디어 입력이 거부될 때

Avatar 미디어 필드는 공개 HTTPS 이미지 URL을 받습니다. Avatar 1.0 사진 입력에는 --type photo --image-url https://...를, Avatar Video에는 필요에 따라 --product-image https://...나 --scene-image-url https://...를 사용하세요.

흔한 원인은 다음과 같습니다.

URL이 HTTPS가 아닙니다.
URL이 localhost나 사설 네트워크를 가리킵니다.
응답이 이미지가 아닙니다.
URL에 쿠키, 인증 헤더, 또는 Sume가 가져오기 전에 만료되는 짧은 수명의 서명이 필요합니다.

비공개 미디어 URL, 서명된 URL, 인증 헤더를 공개 로그에 붙여 넣지 마세요.

이슈 보고하기

다음을 포함해 주세요.

명령어 이름과 플래그(비밀 값은 가린 상태로)
sume version
정리된 에러 코드와 메시지
있다면 request id
Job 관련 문제라면 Job ID
인증이 환경 변수에서 왔는지 로컬 설정에서 왔는지

API 키, 서명된 URL, 비공개 미디어 URL, 원본 프로바이더 페이로드, 이메일, 워크스페이스·사용자 ID는 포함하지 마세요.