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