> ## 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 整合指南 - 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、官網安卓直鏈

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