# 知格科技 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)，示例中的密钥和素材地址均需自行替换。

## 视频生成（异步）

提交视频生成任务后，接口立即返回 `task_id`，视频在后台异步生成。请通过状态查询接口轮询结果。

视频接口会按原文提交 `prompt`，不会自动调用视觉模型改写提示词；`prompt_mode` 仅用于图片生成接口。

### 常用视频模型

| 模型 | 素材规则 | 最高分辨率 |
| --- | --- | --- |
| `minimax-h3` | 最多 9 张图片、1 个视频、3 个音频，素材总计不超过 12 个；无素材时为文生视频 | 2K |
| `minimax-h3gm` | 国漫版；参考素材规则与标准 H3 相同 | 2K |
| `minimax-h3-eos` | 国漫增强版；参考素材规则与标准 H3 相同；选择 1080p 时最长 8 秒 | 1080p |
| `minimax-h3-eoswu` | MiniMax H3 增强版；参考素材规则与标准 H3 相同；选择 1080p 时最长 8 秒 | 1080p |
| `minimaxh3-frames` | 必须正好传 2 张图片，依次作为首帧、尾帧；不支持音频和视频 | 2K |
| `minimax-h3-turbo-frames` | 4 步 Turbo：0 张图为文生视频、1 张图为首帧、2 张图为首尾帧；不支持音频和视频 | 固定 768p |

实际可用模型可能由管理端动态调整，请优先以 `GET /models` 返回结果为准。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名，请从 `GET /models` 获取 |
| `prompt` | string | 是 | 视频描述提示词；最长 7000 字符 |
| `images` | string[] | 否 | 参考图片数组，每项为 URL 或 data URI；数量限制由模型决定 |
| `videos` | string[] | 否 | 参考视频数组，每项为 URL 或 data URI；最多 1 个且仅部分模型支持 |
| `audios` | string[] | 否 | 参考音频数组，每项为 URL 或 data URI；最多 3 个且仅部分模型支持 |
| `duration` | number | 是 | 视频时长（秒），最少 4 秒；两个 EOS 增强工作流选择 1080p 时最长 8 秒；Turbo 首尾帧支持 4～15 秒 |
| `size` | string | 否 | 画布尺寸，格式 `宽x高`，如 `1344x768`；Turbo 首尾帧用它推导宽高比并固定按 768p 生成 |
| `aspect_ratio` | string | 否 | 画面比例；Turbo 首尾帧仅支持 `4:3`、`16:9`、`9:16`，建议显式传入 |
| `negative_prompt` | string | 否 | 负面提示词 |
| `seed` | integer | 否 | 随机种子 |
| `response_format` | string | 否 | OpenAI 兼容字段；视频结果当前以 `url` 返回 |

> **限制说明：**
>
> - 图片：JPG/JPEG、PNG、WEBP、HEIC、HEIF；单张不超过 30MB，宽高均为 256～5760 像素
> - 视频：H.264/AVC、H.265/HEVC，视频内音频须为 AAC 或 MP3；单段 2～15 秒、全部视频总时长不超过 15 秒，单段不超过 50MB
> - 视频宽高均为 256～5760 像素，宽高比须在 2:5～5:2 之间
> - 音频：WAV、MP3；单段 2～15 秒、全部音频总时长不超过 15 秒，单段不超过 15MB
> - 音频不能单独输入，必须同时传入至少一张图片或一段视频
> - 图片、视频和音频混合输入总计最多 12 个文件；请求体不超过 64MB，较大素材建议使用 URL
> - `minimax-h3-turbo-frames` 仅支持 0～2 张图片，不支持参考音频或视频
> - `minimax-h3-eos`、`minimax-h3-eoswu` 使用 1080p 时，`duration` 不能超过 8 秒
> - 速率限制：每分钟 30 次提交、600 次状态查询

### 尺寸与分辨率

推荐使用 `4:3`、`16:9`、`9:16` 三种比例。标准 H3、国漫及传统首尾帧工作流最高支持 2K；两个增强版最高支持 1080p；Turbo 首尾帧固定使用 768p。常用分辨率对照：

| 比例 | 768p | 1080p | 2K |
| --- | --- | --- | --- |
| 4:3 | `1024x768` | `1440x1080` | `2048x1536` |
| 16:9 | `1344x768` | `1920x1080` | `2560x1440` |
| 9:16 | `768x1344` | `1080x1920` | `1440x2560` |

### 请求示例

```http
POST https://zhigekeji.com/api/v1/videos/generations/async
Authorization: Bearer sk-xxxx...
Content-Type: application/json

{
  "model": "minimax-h3",
  "prompt": "图1和图2在图3的场景里喝酒聊天",
  "images": [
    "https://example.com/character1.jpg",
    "https://example.com/character2.jpg",
    "https://example.com/scene.jpg"
  ],
  "audios": [
    "https://example.com/reference_audio.mp3"
  ],
  "duration": 5,
  "size": "768x1344"
}
```

立即返回：

```json
{
  "created": 1716652800,
  "task_id": "6601",
  "status": "pending",
  "object": "video_generation.task"
}
```

### Turbo 首尾帧示例

```http
POST https://zhigekeji.com/api/v1/videos/generations/async
Authorization: Bearer sk-xxxx...
Content-Type: application/json

{
  "model": "minimax-h3-turbo-frames",
  "prompt": "镜头从清晨缓慢过渡到黄昏，人物自然转身看向镜头",
  "images": [
    "https://example.com/first-frame.png",
    "https://example.com/last-frame.png"
  ],
  "duration": 5,
  "size": "1344x768",
  "aspect_ratio": "16:9"
}
```

`minimax-h3-turbo-frames` 不传 `images` 时为文生视频，传 1 张时为首帧生视频，传 2 张时按首帧、尾帧顺序处理。Turbo 所需推理步数、LoRA 和帧索引由服务端自动注入，调用方无需传入。