# 두 개의 API 표면
> **이 장에서 배우는 것**
> 하이퍼팀즈(HyperTeams)가 바깥에 내주는 두 개의 문, 각각이 무엇을 열어주는지, 그리고 켜기
> 전에 반드시 이해해야 할 것.
>
> **API·엔드포인트가 처음이라면** [API란 무엇인가](/guide/it-api)를 먼저 보세요.
## 여기서부터 성격이 바뀝니다
앞의 12장은 **화면에서 쓰는 법**이었습니다. 이 파트는 **다른 프로그램이 이
컴퓨터를 부르게 만드는** 이야기입니다.
그러려면 문을 열어야 하고, 문을 열기 전에 **무엇이 열리는지** 알아야 합니다.
## 문은 정확히 두 개입니다
```mermaid
graph TD
A["/api/* 전체"] --> B["/api/v1
HyperTeams 자신의 REST"]
A --> C["/api/ai
모델 — OpenAI 호환"]
A --> D["그 밖의 모든 /api/*
대시보드 전용"]
B --> B1["Bearer 열쇠"]
C --> C1["Bearer 열쇠"]
D --> D1["브라우저 쿠키
바깥에서 못 부름"]
```
| 접두 | 무엇을 하나 | 인증 |
|---|---|---|
| `/api/v1` | **업무를 시킨다** — 작업 폴더 목록, 업무 생성·조회·이어말하기·중지 | Bearer |
| `/api/ai` | **모델을 부른다** — 대화, 임베딩, 음성, 이미지 | Bearer |
| 나머지 | 대시보드 화면이 쓰는 것 | 쿠키 |
**이 둘 말고는 바깥에서 부를 수 없습니다.** 화면이 쓰는 라우트들은 로그인한
브라우저의 쿠키로만 열립니다.
## 기본값은 꺼짐입니다
가장 중요한 성질입니다.
> **켠 적 없는 설치에서는 이 경로들이 아예 존재하지 않습니다 — 404입니다.**
`401`(권한 없음)이 아니라 `404`(없음)라는 게 의도된 것입니다. 켜지 않은 시스템은
**API가 있다는 사실조차 광고하지 않습니다.**
| 설정 | 기본값 |
|---|---|
| REST 표면 | 꺼짐 |
| 모델 표면 | 꺼짐 |
## 열쇠가 곧 대시보드 비밀번호입니다
여기가 이 장의 핵심입니다.
> **API 열쇠는 별도로 발급되는 값이 아니라 대시보드 비밀번호 그 자체입니다.**
```
Authorization: Bearer <대시보드 비밀번호>
```
이 설계에는 결과가 따라옵니다.
### 결과 1 — 비밀번호가 없으면 켤 수 없습니다
비밀번호를 설정하지 않은 설치는 **대시보드 자체가 인증 없이 도는 전제**(내
컴퓨터에서만 접속)로 서 있습니다. 거기에 "아무 값이나 통과하는 API"를 더하면 그
전제가 깨지는 순간 두 배로 열립니다. 그래서 아예 켜지지 않습니다.
```bash
hyperteams setup # 비밀번호부터
```
### 결과 2 — 열쇠가 퍼지는 곳이 늘어납니다
비밀번호를 Bearer로 쓰기 시작하면 그 값이 이런 데 붙습니다.
```
□ 편집기 설정 파일
□ 자동화 스크립트
□ 다른 컴퓨터의 환경변수
□ CI 설정
```
**하나가 새면 대시보드가 통째로 열립니다.** [터널](/guide/ht-remote-access)에서
"주소를 아는 누구나 시도할 수 있다"고 한 것과 같은 이야기인데, 이쪽은 값이 여러
곳에 복사된다는 점이 다릅니다.
> **그래서 켤 때 자문할 것**: 이 열쇠가 붙을 곳을 전부 셀 수 있습니까? 셀 수
> 없으면 아직 켤 때가 아닙니다.
## 모델 표면은 3단계입니다
REST는 켜짐/꺼짐 둘이지만, 모델 쪽은 **얼마나 여는지**를 고릅니다.
| 모드 | 열리는 것 |
|---|---|
| `off` | 아무것도. 404 |
| **`inference`** | **추론만** — 대화·임베딩·음성·이미지 생성 |
| `full` | 상류 모델 서버의 관리 경로까지 |
`inference`가 열어주는 목록은 정해져 있습니다.
```
/v1/models 목록
/v1/chat/completions 대화
/v1/completions
/v1/embeddings 임베딩
/v1/moderations
/v1/audio/transcriptions 음성 → 글
/v1/audio/speech 글 → 음성
/v1/audio/classification
/v1/images/generations 이미지 생성
/v1/images/inpainting
/v1/images/upscale
```
**이 목록 밖은 `inference`에서 404입니다.** 모델을 내려받거나 서버를 재시작하는
관리 동작은 `full`에서만 열립니다.
> **`inference`부터 시작하세요.** 다른 프로그램에 모델을 빌려주는 목적이라면
> 추론만으로 충분하고, `full`은 그 프로그램이 내 모델 서버를 **관리**할 수 있게
> 하는 것입니다. [최소 권한](/guide/mcp-security)이 여기도 그대로 적용됩니다.
## 두 base 주소
모델 쪽은 안내되는 주소가 둘인데, 헷갈리기 쉬워서 정리합니다.
| 붙이는 대상 | base |
|---|---|
| OpenAI 호환 도구·SDK | `…/api/ai/v1` |
| 다른 HyperTeams 대시보드 | `…/api/ai` |
`/api/ai` 아래가 상류 모델 서버의 루트와 **1:1로 대응**하기 때문에 이렇게 됩니다.
상류 자신이 "루트 아래 `/v1`에 OpenAI 표면"이라 그 중첩이 그대로 따라옵니다.
> ⚠ **중첩이라서 경로가 범위를 강제하지 않습니다.** `…/api/ai/v1`을 안내했다고
> 해서 그 아래로만 갈 수 있는 게 아닙니다 — 범위를 정하는 것은 경로가 아니라
> **`inference` / `full` 모드**입니다.
설정 탭입니다. 두 API 표면을 켜고 끄는 자리도 여기입니다.
## 켜는 순서
```
1. hyperteams setup 으로 비밀번호 설정
2. 설정 화면에서 필요한 표면만 켜기
- 업무를 외부에서 시킬 것 → REST
- 모델을 빌려줄 것 → 모델(inference)
3. 열쇠를 넣을 곳을 목록으로 적어두기
4. 한 곳에서 호출 한 번 성공시키고 멈추기
```
**4번이 중요합니다.** 한 번 성공하면 그다음은 복사입니다. 처음부터 여러 곳에
붙이면 어디가 틀렸는지 못 찾습니다.
## 명세는 어디에 있나
이 시스템은 **OpenAPI 3.1 명세를 스스로 내놓습니다.** 다만 그 명세는 공개
표면이 아니라 **대시보드 게이트 뒤**에 있습니다.
- 로그인한 브라우저에서 문서 화면으로 봅니다
- 외부 도구에 필요하면 내려받아 건네면 됩니다
> 명세가 비밀은 아니지만, **이 시스템이 무엇을 열어 두었는지 광고할 이유도
> 없습니다.** 그래서 열쇠 없이 읽히는 자리에 두지 않았습니다.
## 자주 하는 오해
### "API 키를 따로 발급받는 것 아닌가요?"
아닙니다. **대시보드 비밀번호가 그대로 열쇠입니다.** 그래서 비밀번호를 바꾸면
그 값을 넣어둔 모든 곳을 함께 고쳐야 합니다.
### "켜두면 편하니까 둘 다 켜두면 되지 않나?"
쓰지 않는 표면은 끄는 게 맞습니다. **켜져 있다는 것은 열쇠 하나로 그쪽도
열린다는 뜻**입니다. 모델만 쓸 거면 REST는 꺼두세요.
### "로컬에서만 쓸 건데도 이게 문제가 되나요?"
`localhost`로만 쓴다면 위험은 훨씬 작습니다. 다만
[터널을 여는 순간](/guide/ht-remote-access) 같은 열쇠가 인터넷에서 통합니다.
**터널과 API를 함께 켤 때 비밀번호의 강도가 실제로 중요해집니다.**
---
## 확인
**1. 켜지 않은 시스템에서 API를 부르면 401이 아니라 404가 나오는 이유는?**
답
**켜지 않은 시스템은 API가 있다는 사실조차 알리지 않기 위해서**입니다. 401은
"여기 문이 있는데 열쇠가 틀렸다"를 알려주지만, 404는 문의 존재 자체를 숨깁니다.
**2. API 열쇠가 무엇이고, 그래서 무엇을 조심해야 합니까?**
답
**대시보드 비밀번호 그 자체**입니다. 그래서 편집기 설정·스크립트·환경변수·CI 등
값이 복사되는 곳이 늘어나고, **하나만 새도 대시보드가 통째로 열립니다.** 켜기
전에 열쇠가 붙을 곳을 셀 수 있어야 합니다.
**3. 모델 표면에서 `inference`와 `full`의 차이는?**
답
`inference`는 **추론 경로만** 엽니다 — 대화·임베딩·음성·이미지 생성. `full`은
모델 내려받기나 서버 재시작 같은 **관리 경로까지** 엽니다. 모델을 빌려주는
목적이라면 `inference`로 충분합니다.
---
먼저 업무를 외부에서 시켜봅니다 → [REST로 업무 시키기](/guide/ht-rest-api)