---
title: 문제 해결
description: Sume CLI의 인증, 설정, Job, 미디어 입력, 릴리스 관련 문제를 디버깅하는 방법을 살펴보세요.
---

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

```bash
sume version
sume auth status
sume doctor --agent --json
sume account get --json
```

## API 키가 없을 때

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

```bash
sume login
sume auth status
```

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

```bash
sume login --no-browser
```

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

```bash
sume auth setup --api-key "$SUME_API_KEY"
```

```bash
export SUME_API_KEY="sume_live_..."
export SUME_API_BASE_URL="https://api.sume.com/v1"
```

## API 베이스가 잘못됐을 때

로컬 설정을 확인하세요.

```bash
sume doctor --agent --json
```

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

```text
https://api.sume.com/v1
```

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

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

```bash
sume jobs status <job_id> --agent --json
```

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

```bash
sume jobs result <job_id> --agent --json
```

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

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

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

## 로컬 MCP가 실행되지 않을 때

```bash
sume mcp doctor --json
```

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

## 미디어 입력이 거부될 때

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

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

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

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

## 이슈 보고하기

다음을 포함해 주세요.

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

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