# 概览 (/docs/models)

Dex Buddy 网关对外只有两种模型能力：文案（`kind=chat`）和生图（`kind=image`）。配图不是第三种模型，它是同一条生图渠道，先上传参考图再生成。

插件作者走 [插件开发 → 模型](/docs/plugins/models)，用 `bindModels(ctx)`。直接调 HTTP 的人走下面三篇。

## 对照表 [#对照表]

公开页不请求 `GET /v1/models`。下表手维护；和现网不一致时改这一页。示例里的 `model` 用这里的 ID。你也可以用 Key 自己调目录核对。

| 显示名 | kind | 用途 | 渠道 Model ID |
|--------|------|------|----------------|
| 文案 | `chat` | 补全；识图走同一接口，`messages[].content` 放 `image_url` | `dexbuddy/chat` |
| 生图 | `image` | 按张生图 | `image-standard` |
| 生图 Pro | `image` | 按张生图 | `image-pro` |
| 生图配图 | `image` | 先上传参考图再生成 | 与生图同一 ID |

不要把内部测试名写成对外承诺。

## 准备 Key [#准备-key]

1. 打开 [密钥页](/account/keys) 创建一把用户 API Key。未登录会先到 `/login?next=/account/keys`。
2. 前缀是 `dbh_sk_`。示例里写成 `$DEX_API_KEY`，不要把真实密钥贴进文档或仓库。
3. 请求头：`Authorization: Bearer $DEX_API_KEY`。

Cookie 会话也可以打同一组 `/v1`，主路径写 Key。不要用上游供应商 Key，也不要把管理后台 Cookie 当令牌。

Base URL 是当前网关的 `/v1`，例如 `https://www.dexbuddy.app/v1`。

## 列出模型 [#列出模型]

需要身份。页面本身不会调用这个接口。

```bash
curl -sS "$BASE/v1/models" \
  -H "Authorization: Bearer $DEX_API_KEY"
```

成功是 `{ object: "list", data: [{ id, kind?, ... }] }`。`id` 是渠道 Model ID。文件上传上游不进目录。

## 必须知道的合同 [#必须知道的合同]

- 文案是 OpenAI Chat Completions 代理：body 按官方字段写即可。对外 `model` 是渠道 ID（对照表里的名字），不是上游货源。
- `stream: true` 会被拒绝。网关只做非流式。
- 成功体**没有**顶层 `billing`，也没有上游 `system_fingerprint`。
- 文案错误体是 `{ error: { message, type, code } }`。其它 `/v1` 错误体是 `{ ok: false, code, error }`。
- 报价可选：`POST /v1/billing/quote`。它不替代真正的补全或生图。

## 往下读 [#往下读]

- [文案怎么用](/docs/models/chat)
- [生图怎么用](/docs/models/images)
- [生图配图怎么用](/docs/models/reference)