> ## 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 整合指南 - 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.