# 빠른 시작 가이드

이 가이드에서는 자격증명 발급부터 첫 API 호출까지의 과정을 안내합니다.

## 두 가지 사용 경로

| 사용 시나리오                                              | 인증               | 가이드                                                                                                |
| ---------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------- |
| AI 어시스턴트(Claude / Cursor / VS Code)에서 자연어로 사용 | OAuth (내장)       | [MCP 서버 설정](mcp-setup.md) → `gency-mcp login` 한 번이면 끝. **이 빠른 시작은 건너뛰어도 됩니다.** |
| 자신의 서버/스크립트에서 REST API 직접 호출                | API Key 또는 OAuth | 아래 절차                                                                                             |

## 사전 준비

아래 세 가지가 모두 끝나야 첫 호출이 성공합니다. 자세한 절차는 [자격증명 발급 가이드](credentials.md)를 참조하세요.

1. GENCY 개발자 계정 ([developers.gency.ai](https://developers.gency.ai))
2. 앱 생성 후 **권한(스코프) 저장** — 앱을 만들면 스코프가 비어 있는 상태로 시작합니다. 앱 목록의 **권한 관리**에서 필요한 스코프를 저장하지 않으면 아래 호출이 모두 실패합니다
3. 앱 상세에서 **API Key 활성화**

> 스코프를 저장하지 않으면 `400` 과 함께 `Insufficient scope. Required: <스코프>` 가 돌아옵니다. 키를 재발급해도 해결되지 않습니다 — [에러 코드 레퍼런스](error-codes.md#스코프-관련-에러) 참조.

어떤 스코프가 필요한지는 그 `Required:` 값이 알려줍니다. 예를 들어 아래 3번(크레딧 조회)은 `team:read`, 사용자 조회는 `user:read` 를 요구합니다. 조회만 할 계획이라도 생성 호출(2번)은 쓰기 스코프가 필요하니, 쓸 엔드포인트에 맞춰 저장하세요.

> 아래 예제는 자신의 코드에서 직접 호출하는 형태입니다. gency-mcp 에는 API Key 를 넣지 마세요 — MCP 는 OAuth 만 사용합니다.

## 1. 팀 정보 확인

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  https://openapi.gency.ai/openapi/v1/teams/me
```

응답:

```json
{
  "data": {
    "teamId": "team_001",
    "teamName": "내 팀",
    "plan": "BASIC"
  }
}
```

## 2. 워크스페이스 생성

```bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "첫 워크스페이스"}' \
  https://openapi.gency.ai/openapi/v1/workspaces
```

## 3. 크레딧 잔액 확인

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  https://openapi.gency.ai/openapi/v1/usage/credits
```

## 4. 템플릿 조회

```bash
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://openapi.gency.ai/openapi/v1/templates?workspaceId=YOUR_WORKSPACE_ID"
```

## 다음 단계

- [상품 생성 플로우](product-creation-flow.md): 이미지 업로드부터 AI 상품 이미지 생성까지
- [Webhook 수신](webhook-receiving.md): 비동기 결과 알림 설정
- [MCP 서버 설정](mcp-setup.md): AI 어시스턴트에서 GENCY API 사용