# APICLD 客户接入指南

更新时间：2026-05-26

这是一份给客户的最短接入说明。拿到账号和 API Key 后，只需要保存好 Base URL、API Key 和默认模型。

## 基础信息

```text
API Base URL: https://api.apicld.com/v1
API Key: APICLD 发放的完整密钥
默认模型: custom
充值与开通: 微信 15574301921，或使用管理员发放的兑换码
```

OpenAI 兼容客户端通常只需要改两项：

- `base_url` 改成 `https://api.apicld.com/v1`
- `api_key` 改成 APICLD 发给你的完整密钥

## 账户与计费

- APICLD 使用统一 `quota` 余额计费，属于一次性充值，不是包月。
- 同一个 APICLD Key 可调用账号已开通的模型。
- 渠道、倍率、风控和路由由管理员维护，客户不需要自行配置。
- 当前续费方式是人工收款 + 后台加余额，或使用兑换码充值。

## 常用模型

- `custom`：Codex / Responses API 推荐默认值。
- `gpt-5.4-mini`：日常文本调用。
- `gpt-5.4`：更高质量文本任务。
- `gpt-image-2`：图片生成。

如果你不确定该填哪个模型，优先填 `custom`。

## Python 示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="你的 APICLD 密钥",
    base_url="https://api.apicld.com/v1"
)

resp = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "你好"}]
)

print(resp.choices[0].message.content)
```

## 图片生成

```python
from openai import OpenAI

client = OpenAI(
    api_key="你的 APICLD 密钥",
    base_url="https://api.apicld.com/v1"
)

image = client.images.generate(
    model="gpt-image-2",
    prompt="一个简洁的蓝色云朵图标，白色背景",
    size="1024x1024"
)
```

## Codex 配置

Codex / Responses API 客户端请按下面填写：

```text
Provider: OpenAI Compatible / Custom OpenAI
Base URL: https://api.apicld.com/v1
API Key: APICLD 发放的完整密钥
Model: custom
```

不要选择 `OpenAI Official`。那会直接走官方接口，不会使用 APICLD 余额和权限。

## 常见错误

`401 Invalid token`

- API Key 错误、复制不完整，或令牌已被禁用。
- 请确认使用的是 APICLD 发放的完整密钥。

`No available channel`

- 当前账号没有该模型权限，或当前没有可用上游渠道。
- Codex 请优先使用 `custom`，图片生成请使用 `gpt-image-2`。

`base_url 缺失`

- Provider 选错了，或没有填写 Base URL。
- 请确认 Base URL 是 `https://api.apicld.com/v1`。

## 报错时发给管理员的信息

```text
1. 报错截图
2. Base URL 截图
3. Model 填写内容
4. 大概调用时间
5. 账号名或令牌名称
```

不要在群里发送完整 API Key。