# 知格科技 API 文档

通过统一的 API 接入对话、图片与视频生成，可用于应用开发及智能体工具对接。

- 文档地址：[API 文档](https://zhigekeji.com/docs)
- Base URL：`https://zhigekeji.com/api/v1`
- 认证方式：`Authorization: Bearer <API_KEY>`
- JSON 请求使用 `Content-Type: application/json`
- 在[控制台创建 API Key](https://zhigekeji.com/console/api-keys)，示例中的密钥和素材地址均需自行替换。

## 智能体接入指南

点击「复制本文」后，将 Markdown 粘贴给你的编程助手或智能体，即可用它编写接口调用工具。也可直接提供[完整 Markdown 文档](https://zhigekeji.com/docs.md)，方便智能体读取。

### 接入配置

| 配置 | 值 |
| --- | --- |
| Base URL | `https://zhigekeji.com/api/v1` |
| API Key | 从服务端环境变量 `ZHIGE_API_KEY` 读取 |
| 认证请求头 | `Authorization: Bearer <API_KEY>` |
| JSON 请求头 | `Content-Type: application/json` |
| 模型发现 | `GET /models`，使用返回的 `name` |

### 将接口封装为智能体工具

在你的智能体框架中，将需要的 HTTP 接口封装为工具，并根据下面的输入与返回值处理结果。

| 能力 | 请求 | 输入与结果 |
| --- | --- | --- |
| 对话 | `POST /chat/completions` | 传入 `model`、`messages`；读取 `choices[0].message.content` |
| 同步图片 | `POST /images/generations` | 传入 `model`、`prompt`；读取 `data` 中的 `url` 或 `b64_json` |
| 异步图片 | `POST /images/generations/async` | 保存返回的 `task_id`；通过 `GET /images/generations/status?task_id=...` 查询 |
| 异步视频 | `POST /videos/generations/async` | 传入 `model`、`prompt`、`duration`；保存 `task_id`，通过 `GET /videos/generations/status?task_id=...` 查询 |
| 取消视频 | `POST /videos/generations/cancel` | 传入 `task_id`，检查返回的 `cancelled` 字段 |

### 可直接交给智能体的接入说明

```text
请为我的应用接入知格科技 API，并遵循以下规则：

1. Base URL 使用 https://zhigekeji.com/api/v1；API Key 从服务端环境变量 ZHIGE_API_KEY 读取。
2. 每个请求携带 Authorization: Bearer <API_KEY>；JSON 请求携带 Content-Type: application/json。
3. 调用 GET /models 获取当前可用模型。使用返回的 name 作为 model，并根据 type 选择 text、image 或 video。
4. 对话调用 POST /chat/completions，传入 model 和 messages，读取 choices[0].message.content。
5. 图片和视频优先使用异步生成接口。提交成功后保存 task_id，每隔 5～10 秒查询对应的状态接口，并设置总等待超时。
6. pending 和 processing 表示尚未完成；completed 时读取 data 数组；failed 或 cancelled 时停止轮询并显示错误。
7. 状态查询使用 processing；视频任务列表的生成中筛选值为 running。
8. 素材数量、时长和尺寸按所选模型的接口说明填写，URL 和示例模型名需替换为真实可用值。
9. 429 时退避重试；401 检查密钥；402 检查余额与密钥额度；400 / 422 检查参数和返回的错误信息。
10. 提交生成请求后若网络超时，先检查任务记录，避免盲目重复提交。任务查询超时并不代表服务端已取消任务。
11. 将密钥保存在服务端，提供配置项、错误处理及可运行的调用示例。

完整接口文档：https://zhigekeji.com/docs.md
```

### 异步任务的处理顺序

1. 提交任务，异步生成接口成功时返回 HTTP `202` 和 `task_id`。
2. 保存任务 ID，以便重新打开应用后继续查询。
3. 每隔 5～10 秒查询状态，并设置轮询截止时间。
4. `completed` 时读取 `data` 中的结果；`failed` / `cancelled` 时停止轮询。
5. 轮询超时后保留任务 ID，允许用户再次查询或通过视频取消接口取消任务。

详细参数见[图片生成](https://zhigekeji.com/docs#openai-images)、[视频生成](https://zhigekeji.com/docs#openai-video-async)与[错误码](https://zhigekeji.com/docs#errors)。