> ## 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.

# ChatBox에서 Ace Data Cloud 사용하기

> Platform API guide - Ace Data Cloud

[ChatBox](https://chatboxai.app/)는 Windows, macOS, Linux, iOS, Android 및 Web을 지원하는 오픈 소스 AI 클라이언트입니다. 「OpenAI API」 유형의 사용자 지정 서비스 제공업체를 지원하므로 Ace Data Cloud에 직접 연결할 수 있습니다. 이 글에서는 구성 절차를 소개합니다.

## 신청 절차

ChatBox에서 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의 모델 서비스를 무료로 체험할 수 있습니다.

## ChatBox 다운로드

[ChatBox 공식 웹사이트](https://chatboxai.app/)에서 플랫폼에 맞게 다운로드하거나, 설치가 필요 없는 [Web 버전](https://web.chatboxai.app/)을 직접 사용하세요:

* 데스크톱: Windows `.exe`, macOS `.dmg`(Intel / Apple Silicon 구분), Linux AppImage
* 모바일: App Store, Google Play, 공식 웹사이트 Android 직접 링크

## Ace Data Cloud 구성

ChatBox를 시작하고 **설정 → 모델 → 사용자 지정 Provider 추가**로 이동하여 **API Mode**를 **OpenAI API Compatible**으로 설정한 다음, 다음을 입력하세요:

| 필드 | 값 | 설명 |
| - | - | - |
| API 키 | 당신의 Ace Data Cloud Token | 콘솔에서 복사한 Token |
| API Host | `https://api.acedata.cloud` | 루트 도메인만 입력하고, **`/openai` 또는 `/v1`을 포함하지 마세요** |
| API Path | `/v1/chat/completions` | ChatBox 기본값은 `/chat/completions`이므로, 이것으로 수동 변경해야 합니다 |

![ChatBox Ace Data Cloud Provider 구성 화면](https://cdn.acedata.cloud/3789c8e3dd4d.png)

ChatBox의 요청 경로는 `{API Host} + {API Path}`이므로, Host에는 루트 도메인만 입력하면 됩니다:

| API Host | 최종 요청 | 결과 |
| - | - | - |
| `https://api.acedata.cloud` | `https://api.acedata.cloud/v1/chat/completions` | 올바름 |
| `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404（`/openai` 아래에 `/v1`이 없음） |
| `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/v1/chat/completions` | 404 |

ChatBox는 `/v1/models`를 자동으로 호출하지 않으므로, 모델 설정 페이지 하단의 「사용자 지정 모델」 입력란에 모델 ID를 수동으로 입력해야 합니다(한 줄에 하나씩). 저장한 후 대화 화면의 모델 드롭다운에서 선택할 수 있습니다. 기능 스위치, 컨텍스트 창 및 출력 상한은 선택한 모델의 현재 계약에 따라 입력해야 하며, 다른 모델의 값을 그대로 복사하지 마세요.

## 모델 선택

모델 목록은 계속 업데이트됩니다. 클라이언트가 자동으로 불러오는 모델 목록을 우선 사용하세요. 수동으로 입력해야 하는 경우 먼저 `GET https://api.acedata.cloud/v1/models`를 요청하여 현재 모델 ID를 가져온 후, 클라이언트가 지원하는 컨텍스트, 이미지 및 도구 호출 기능에 따라 선택하세요.

## 연결 검증

문제가 ChatBox에 있는지 네트워크에 있는지 확실하지 않은 경우, 먼저 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)에서 충전하면 됩니다.

## 자주 묻는 질문

### 404 Not Found가 표시됨

일반적으로 API Host에 `/openai` 또는 `/v1`을 추가로 넣었기 때문입니다. Host에는 `https://api.acedata.cloud`만 입력하고, 경로는 기본값인 `/v1/chat/completions`에 맡기세요.

### 401 / token\_mismatched가 표시됨

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

### 모델 드롭다운에 모델이 보이지 않음

ChatBox는 모델 목록을 자동으로 가져오지 않으므로, 「사용자 지정 모델」 입력란에 모델 ID를 수동으로 입력하고 저장해야 합니다.

### ChatBox에서 이미지를 생성하고 싶음

Ace Data Cloud의 이미지 생성은 독립적인 Images API(`/openai/images/generations`)이며, 대화 인터페이스와는 경로가 다릅니다. ChatBox의 이미지 진입점은 직접 연결할 수 없습니다. 그림을 생성해야 한다면 [이미지 생성 API 문서](https://platform.acedata.cloud/documents/openai-images-generations)를 참고하여 curl / SDK로 호출하세요.

## 더 알아보기

* [ChatBox 공식 웹사이트](https://chatboxai.app/) ｜ [ChatBox GitHub](https://github.com/chatboxai/chatbox)
* [ChatBox OpenAI 호환 서비스 연결 공식 가이드(BYOK)](https://chatboxai.app/en/guide/byok/openai)
* [Ace Data Cloud OpenAI Chat Completions API 문서](https://platform.acedata.cloud/documents/openai-chat-completions)
* [Ace Data Cloud 이미지 생성 API 문서](https://platform.acedata.cloud/documents/openai-images-generations)
* [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.