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