> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Jan에서 Ace Data Cloud 사용하기

> Platform API guide - Ace Data Cloud

[Jan](https://jan.ai/)은 오프라인 우선 오픈 소스 AI 데스크톱 클라이언트로, 로컬에서 모델을 실행할 수 있을 뿐만 아니라 **Remote Engine**을 통해 OpenAI 호환 엔드포인트에 연결할 수도 있습니다. 이 문서에서는 Ace Data Cloud에 연결하는 방법을 소개합니다.

## 신청 절차

Jan에서 Ace Data Cloud에 연결하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)로 이동하여 API Token을 발급받고, 나중을 위해 보관해 두세요.

![Ace Data Cloud API Key 발급](https://cdn.acedata.cloud/dvc3cg.jpg)

아직 로그인하거나 가입하지 않은 경우 로그인 페이지로 자동 이동하여 가입 및 로그인을 안내하며, 로그인 및 가입 후에는 현재 페이지로 자동 돌아옵니다.

최초 신청 시 무료 크레딧이 제공되어 Ace Data Cloud의 모델 서비스를 무료로 체험할 수 있습니다.

## Jan 다운로드

[Jan 공식 웹사이트](https://jan.ai/)에서 플랫폼별(Windows, macOS, Linux)로 다운로드하세요. Apple Silicon 기기는 최상의 성능을 위해 arm64 패키지를 다운로드하세요.

## Ace Data Cloud 구성

Jan은 모델을 **Local Engine**(로컬 실행)과 **Remote Engine**(타사 API)의 두 가지 유형으로 구분합니다. Ace Data Cloud는 OpenAI 호환 프로토콜을 사용하므로 Remote Engine으로 연결합니다.

Jan을 열고 **Settings → Model Providers**로 이동하여 **OpenAI** 카드를 찾아 편집하세요.

| 필드 | 값 | 설명 |
| - | - | - |
| API Key | 당신의 Ace Data Cloud Token | 콘솔에서 복사한 Token |
| Base URL | `https://api.acedata.cloud/v1` | **반드시 `/v1`으로 끝나야 하며, 끝에 슬래시를 붙이지 마세요** |

> Base URL이 `/v1`으로 끝나야 하는 것은 Jan 공식 문서의 명확한 규약입니다. 기존 OpenAI 구성을 덮어쓰고 싶지 않다면 「+ Add Provider」로 `openai-compatible` 유형의 Provider를 새로 만들고 동일한 내용을 입력할 수 있습니다.

![Jan AceDataCloud Provider 추가 구성 화면](https://cdn.acedata.cloud/26017d28afa1.png)

사용자 지정 Provider를 저장한 후 Jan은 먼저 `{Base URL}/models`를 호출하여 모델 목록을 가져오려고 시도합니다. 현재 버전이나 엔드포인트가 사용 가능한 목록을 반환하지 않는 경우, 같은 편집 페이지 하단에서 **+ Add Model**을 눌러 모델 ID를 수동으로 입력하세요. 추가 후 모델은 좌측 상단 드롭다운에 나타나며, 원격 / 로컬을 구분하기 위한 「Cloud」 아이콘이 표시됩니다.

![Jan Provider 모델 관리 화면](https://cdn.acedata.cloud/ae485550946c.png)

> `MODEL_ID`는 자리 표시자입니다. [모델 카탈로그](https://platform.acedata.cloud/models)에서 확인한 후 대상 모델 이름으로 바꾸세요. 정확한 확인이 필요한 경우 `/v1/models` 응답의 `id` 값을 기준으로 하세요. 이 값은 API `model` 파라미터에서 사용하는 모델 이름이며, 서비스 또는 API의 UUID가 아닙니다.

## 모델 선택

[모델 카탈로그](https://platform.acedata.cloud/models)는 지속적으로 업데이트됩니다. 클라이언트가 자동으로 불러온 모델 목록을 우선 사용하세요. 수동으로 입력해야 하는 경우 먼저 `GET https://api.acedata.cloud/v1/models`를 요청하고, 응답의 `data` 배열에서 대상 모델의 `id` 값을 복사한 다음 클라이언트가 지원하는 컨텍스트, 이미지 및 도구 호출 기능에 따라 선택하세요.

## 연동 확인

문제가 Jan에 있는지 네트워크에 있는지 확실하지 않다면, 먼저 curl로 엔드포인트를 직접 확인할 수 있습니다(`{token}`을 당신의 Token으로 바꾸세요).

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

OpenAI 호환 `chat.completion` 객체가 반환되면 Token과 엔드포인트가 모두 준비되었음을 의미합니다. `HTTP 403 used_up`이 반환되면 Token은 유효하지만 잔액이 부족하다는 의미이므로 [콘솔](https://platform.acedata.cloud/console/applications)에서 충전하면 됩니다.

## 고급: 로컬 + 클라우드 혼합

Jan에는 활성화할 수 있는 로컬 OpenAI 호환 API Server(Settings → Local API Server)가 내장되어 있습니다. 활성화 후 `http://localhost:1337/v1/chat/completions`에서 수신 대기하며, 다운로드한 로컬 모델을 실행합니다. 이렇게 하면 LangChain / LlamaIndex 등의 프레임워크에서 Base URL을 로컬로 지정하여 무료로 디버깅하고, 복잡한 작업은 Ace Data Cloud 원격 모델로 전환할 수 있습니다. 모델을 전환해도 대화 컨텍스트는 사라지지 않습니다.

## 자주 묻는 질문

### Connection error 또는 404가 표시됨

일반적으로 Base URL에서 `/v1`이 누락된 경우입니다. `https://api.acedata.cloud/v1`으로 변경하세요(반드시 `/v1`으로 끝나야 하며, `.../openai/v1`으로 작성하지 마세요).

### 401 Unauthorized가 표시됨

API Key에 Ace Data Cloud의 Token이 붙여넣어졌는지(`Bearer` 접두사 없이, 불필요한 공백 없이), 그리고 해당 애플리케이션의 잔액이 충분한지 확인하세요.

### 원격 모델이 드롭다운에 나타나지 않음

먼저 모델 새로고침 버튼을 눌러 `/v1/models`를 호출하세요. 자동 검색에 실패하면 수동으로 **+ Add Model**을 선택하고, 카탈로그의 모델 `id` 값을 그대로 추가하세요.

### 이미지를 업로드하여 모델이 분석하도록 할 수 있나요

가능하지만, 현재 모델 카탈로그에서 시각 입력을 명확히 지원하는 모델을 선택해야 합니다.

## 더 알아보기

* [Jan 공식 웹사이트](https://jan.ai/) ｜ [Jan GitHub](https://github.com/menloresearch/jan) ｜ [Jan 문서](https://jan.ai/docs)
* [Jan 사용자 지정 OpenAI 호환 엔드포인트 연결 공식 문서](https://jan.ai/docs/desktop/remote-models/custom-endpoint)
* [Jan 로컬 API Server 공식 문서](https://jan.ai/docs/desktop/api-server)
* [Ace Data Cloud OpenAI Chat Completions API 문서](https://platform.acedata.cloud/documents/openai-chat-completions)
* [Ace Data Cloud 서비스 목록](https://platform.acedata.cloud/documents)
* [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.