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

## 快速入门

通过一个 Base URL，接入对话、图片与视频生成。对话和同步图片接口兼容 OpenAI SDK，几分钟即可完成第一次调用。

### 1. 创建 API Key

前往[控制台 · API 密钥](https://zhigekeji.com/console/api-keys)创建密钥，并将它保存在服务端环境变量中。以下 cURL 示例适用于 Bash / zsh：

```bash
export ZHIGE_API_KEY="sk-your-api-key"
```

### 2. 获取可用模型

Base URL 为 `https://zhigekeji.com/api/v1`。先查询模型列表，再选择对应能力的模型：

```bash
curl "https://zhigekeji.com/api/v1/models" \
  -H "Authorization: Bearer $ZHIGE_API_KEY"
```

模型列表的 `type` 区分 `text`、`image` 和 `video`。调用时将返回的 `name` 填入 `model`，示例中的模型名称需替换为当前账号实际可用的名称。

### 3. 发起第一次对话

```bash
curl "https://zhigekeji.com/api/v1/chat/completions" \
  -H "Authorization: Bearer $ZHIGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-27B",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ]
  }'
```

成功后从 `choices[0].message.content` 读取回答。需要流式输出时传入 `stream: true`，按 SSE 格式读取，收到 `data: [DONE]` 后结束。

### 继续构建

- [使用 Python / Node.js SDK](https://zhigekeji.com/docs#openai-sdk)
- [生成与编辑图片](https://zhigekeji.com/docs#openai-images)
- [提交异步视频任务](https://zhigekeji.com/docs#openai-video-async)
- [将 API 接入智能体](https://zhigekeji.com/docs#agent-integration)

---

## 认证方式

所有模型推理接口使用 API 密钥认证，在请求头中添加 `Authorization: Bearer sk-xxxx...`。

```http
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

API 密钥以 `sk-` 开头，可在控制台的 [API 密钥管理](https://zhigekeji.com/console/api-keys) 页面创建和查看。

---

## API 密钥管理

在 [控制台 - API 密钥](https://zhigekeji.com/console/api-keys) 页面可以创建、查看和管理密钥。

### 创建密钥

点击「创建密钥」按钮，输入名称和速率限制即可生成。密钥格式为 `sk-xxxx...`，创建后请立即复制保存。

```text
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

请通过服务端环境变量保存密钥。调用前确认账户余额及该密钥的可用额度，撤销的密钥需要重新创建后更新调用配置。

---

## 智能体接入指南

点击「复制本文」后，将 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)。

---

## OpenAI SDK 接入

对话和图片生成接口兼容 OpenAI SDK，只需修改 `base_url` 和 `api_key`。视频生成、状态查询和取消是扩展接口，请按上方 HTTP 示例调用。

### Python（openai 库）

安装依赖：`pip install openai`。先设置环境变量 `ZHIGE_API_KEY`，并将示例模型名称替换为模型列表中实际可用的 `name`。

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHIGE_API_KEY"],
    base_url="https://zhigekeji.com/api/v1"
)

# LLM 对话补全
response = client.chat.completions.create(
    model="Qwen3-27B",
    messages=[
        {"role": "user", "content": "你好，请介绍一下自己"}
    ]
)
print(response.choices[0].message.content)

# 多模态对话（带参考图）
response = client.chat.completions.create(
    model="Qwen3-27B",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请描述这张图片"},
                {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
            ]
        }
    ]
)
print(response.choices[0].message.content)

# 文生图
response = client.images.generate(
    model="ernie-image",
    prompt="一个穿着棒球服的少女，树下",
    size="768x1344"
)
print(response.data[0].url)
```

### Node.js（openai 库）

安装依赖：`npm install openai`。使用支持 ES Module 的 Node.js 项目，并在运行前设置环境变量 `ZHIGE_API_KEY`。

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ZHIGE_API_KEY,
  baseURL: 'https://zhigekeji.com/api/v1',
});

// LLM 对话补全
const chatResponse = await client.chat.completions.create({
  model: 'Qwen3-27B',
  messages: [
    { role: 'user', content: '你好，请介绍一下自己' }
  ],
});
console.log(chatResponse.choices[0].message.content);

// 多模态对话（带参考图）
const visionResponse = await client.chat.completions.create({
  model: 'Qwen3-27B',
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: '请描述这张图片' },
        { type: 'image_url', image_url: { url: 'https://example.com/photo.jpg' } }
      ]
    }
  ],
});
console.log(visionResponse.choices[0].message.content);

// 图片生成
const imageResponse = await client.images.generate({
  model: 'ernie-image',
  prompt: '一个穿着棒球服的少女，树下',
  size: '768x1344',
});
console.log(imageResponse.data[0].url);
```

### cURL

```bash
# LLM 对话补全
curl https://zhigekeji.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-27B",
    "messages": [{"role": "user", "content": "你好，请介绍一下自己"}]
  }'

# 多模态对话（带参考图）
curl https://zhigekeji.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3-27B",
    "messages": [{"role": "user", "content": [
      {"type": "text", "text": "请描述这张图片"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]}]
  }'

# 图片生成
curl https://zhigekeji.com/api/v1/images/generations \
  -H "Authorization: Bearer sk-xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-image",
    "prompt": "一个穿着棒球服的少女，树下",
    "size": "768x1344"
  }'

# 异步视频生成（H3 Turbo 首尾帧）
curl https://zhigekeji.com/api/v1/videos/generations/async \
  -H "Authorization: Bearer sk-xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'
```

---

## OpenAI 兼容接口说明

平台提供 OpenAI 风格的接口，可使用 OpenAI SDK 或兼容客户端调用。支持 LLM 对话补全（含多模态参考图），以及工作流或独立推理服务驱动的图片、视频生成。

**核心流程**：获取模型列表 → 调用对话、图片或视频接口 → 获取同步结果或轮询异步任务

| 项目 | 值 |
| --- | --- |
| Base URL | `https://zhigekeji.com/api/v1` |
| 认证方式 | Bearer Token（API Key 或登录 Token） |
| Content-Type | `application/json` |

---

## 模型列表

获取当前账号可调用的模型，兼容 OpenAI `/v1/models` 格式，包含对话、图片和视频模型。应用上下线后列表会动态变化，调用前建议以此接口返回的 `name` 为准。

```http
GET https://zhigekeji.com/api/v1/models
Authorization: Bearer sk-xxxx...
```

返回示例：

```json
{
  "object": "list",
  "data": [
    {
      "object": "model",
      "owned_by": "zhigekeji",
      "name": "Qwen3-27B",
      "description": "通义千问3 27B 对话模型",
      "type": "text"
    },
    {
      "object": "model",
      "owned_by": "zhigekeji",
      "permission": [],
      "name": "ernie-image",
      "description": "图片生成模型",
      "type": "image",
      "price": 0.2,
      "price_type": "once"
    },
    {
      "object": "model",
      "owned_by": "zhigekeji",
      "permission": [],
      "name": "minimax-h3-turbo-frames",
      "description": "H3 Turbo 文生、首帧和首尾帧视频",
      "type": "video",
      "price": 0.5,
      "price_type": "once"
    }
  ]
}
```

`price` 和 `price_type` 由管理端配置，示例数值仅用于展示返回结构，请以接口实时结果为准。

---

## 对话补全

兼容 OpenAI `/v1/chat/completions` 格式，调用 LLM 模型进行对话。支持流式（SSE）和非流式两种模式，支持多模态消息（参考图）。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名称，以模型列表返回的 name 为准 |
| `messages` | array | 是 | 消息数组，支持纯文本和多模态格式 |
| `stream` | boolean | 否 | 是否流式返回，默认 `false` |
| `temperature` | number | 否 | 生成温度，0-2 |
| `max_tokens` | integer | 否 | 最大生成 token 数 |
| `top_p` | number | 否 | Top-P 采样参数 |

### 纯文本对话

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

{
  "model": "Qwen3-27B",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手"},
    {"role": "user", "content": "你好，请介绍一下自己"}
  ],
  "stream": false
}
```

### 带参考图的多模态对话

在 `messages` 中使用 `image_url` 类型传入图片，支持 URL 和 base64 格式：

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

{
  "model": "Qwen3-27B",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "请描述这张图片的内容"},
        {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
      ]
    }
  ]
}
```

使用 base64 格式：

```json
"content": [
  {"type": "text", "text": "请描述这张图片"},
  {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ..."}}
]
```

非流式返回示例：

```json
{
  "id": "chatcmpl-a1b2c3d4",
  "object": "chat.completion",
  "created": 1716652800,
  "model": "Qwen3-27B",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个AI助手..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 50,
    "total_tokens": 70
  }
}
```

流式返回（`stream: true`）使用 SSE 格式，每个 chunk 兼容 OpenAI `chat.completion.chunk` 格式，最终以 `data: [DONE]` 结束。

---

## 图片生成

兼容 OpenAI `/v1/images/generations` 格式。既支持文生图，也支持部分模型使用参考图进行编辑；参考图数量和尺寸处理方式由所选模型决定。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名，以 `GET /v1/models` 返回的 `name` 为准 |
| `prompt` | string | 是 | 图片描述提示词，最长 4000 字符 |
| `size` | string | 否 | 图片尺寸，如 `768x1344` |
| `response_format` | string | 否 | 返回格式：`url`（默认）或 `b64_json` |
| `images` | string[] | 否 | 参考图片数组，每项为 URL 或 data URI；数量上限由模型决定 |
| `prompt_mode` | string | 否 | `add`（默认，保留原提示词；有参考图时补充图片信息）或 `optimize`（结合参考图优化提示词） |

> 可用图片模型、参考图数量和支持尺寸可能由管理端调整，请以 `GET /v1/models` 返回结果及接口校验结果为准。

### 基础图片生成

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

{
  "model": "ernie-image",
  "prompt": "一个穿着棒球服的少女，树下",
  "size": "768x1344",
  "response_format": "url"
}
```

### 带参考图的图片生成

部分图片模型支持参考图，图片顺序即参考顺序；具体数量限制以所选模型为准：

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

{
  "model": "ernie-image",
  "prompt": "保留人物五官和发型，将背景改为明亮的城市咖啡馆",
  "images": [
    "https://example.com/reference.jpg"
  ],
  "size": "768x1344"
}
```

返回示例：

```json
{
  "created": 1716652800,
  "data": [
    {
      "url": "http://host/view?filename=00001_.png"
    }
  ]
}
```

---

## 异步图片生成

适用于需要批量生成或对响应时间不敏感的场景。接口立即返回 `task_id`，图片生成在后台异步执行，通过状态查询接口获取结果。

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

{
  "model": "ernie-image",
  "prompt": "保持人物特征，将背景改为雪山",
  "images": [
    "https://example.com/reference.jpg"
  ],
  "size": "768x1344"
}
```

请求参数与同步接口相同，立即返回：

```json
{
  "created": 1716652800,
  "task_id": "42",
  "status": "pending",
  "object": "image_generation.task"
}
```

---

## 生图状态查询

通过异步接口返回的 `task_id` 查询图片生成状态和结果。

```http
GET https://zhigekeji.com/api/v1/images/generations/status?task_id=42
Authorization: Bearer sk-xxxx...
```

### 状态码说明

| status | 说明 |
| --- | --- |
| `pending` | 任务排队中 |
| `processing` | 正在生成 |
| `completed` | 生成完成 |
| `failed` | 生成失败 |
| `cancelled` | 任务已取消 |

### 完成状态返回示例

```json
{
  "created": 1783476000,
  "task_id": "42",
  "status": "completed",
  "data": [
    {
      "url": "http://host/view?filename=00001_.png"
    }
  ],
  "completed_at": 1783476090
}
```

失败或取消时仅返回通用错误信息，具体执行错误保留在管理端任务详情中。

---

## 视频生成（异步）

提交视频生成任务后，接口立即返回 `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 和帧索引由服务端自动注入，调用方无需传入。

---

## 视频状态查询

通过异步接口返回的 `task_id` 轮询视频生成状态和结果。建议轮询间隔 5-10 秒。

```http
GET https://zhigekeji.com/api/v1/videos/generations/status?task_id=6601
Authorization: Bearer sk-xxxx...
```

### 状态码说明

| status | 说明 |
| --- | --- |
| `pending` | 任务排队中 |
| `processing` | 正在生成 |
| `completed` | 生成完成 |
| `failed` | 生成失败 |
| `cancelled` | 任务已取消 |

### 完成状态返回示例

```json
{
  "created": 1786586400,
  "task_id": "6601",
  "status": "completed",
  "data": [
    {
      "url": "https://host/view?filename=video_6601.mp4"
    }
  ],
  "completed_at": 1786586730
}
```

失败或取消时仅向调用方返回通用错误信息，具体执行错误保留在管理端任务详情中。

---

## 批量视频状态查询

一次查询 1～100 个任务，适合画布同时轮询多个视频节点。任务 ID 必须为整数且不能重复。

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

{
  "task_ids": [6601, 6602, 6603]
}
```

```json
{
  "data": [
    {
      "created": 1786586400,
      "task_id": "6601",
      "status": "completed",
      "data": [{"url": "https://host/view?filename=video_6601.mp4"}],
      "completed_at": 1786586730
    },
    {
      "created": 1786586450,
      "task_id": "6602",
      "status": "processing"
    }
  ],
  "missing_task_ids": ["6603"]
}
```

---

## 视频任务列表

查询当前用户的视频生成任务列表，支持按状态筛选。

```http
GET https://zhigekeji.com/api/v1/videos/generations/list?status=completed&limit=20&page=1
Authorization: Bearer sk-xxxx...
```

### 查询参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `status` | string | 否 | 按数据库状态筛选：`pending` / `running` / `completed` / `failed` / `cancelled` |
| `limit` | integer | 否 | 每页数量，默认 20，最大 100 |
| `page` | integer | 否 | 页码，默认 1 |

返回示例：

```json
{
  "object": "list",
  "data": [
    {
      "task_id": "6601",
      "status": "completed",
      "model": "workflow-12",
      "model_name": "minimax-h3-turbo-frames",
      "created_at": "2026-08-13T10:00:00Z",
      "completed_at": "2026-08-13T10:05:30Z"
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}
```

任务列表不返回生成结果；请使用视频状态查询接口读取完成任务的 `data`。

---

## 取消视频任务

取消当前用户的排队中或生成中任务。已完成或已失败任务不会被改写为取消状态。

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

{
  "task_id": "6602"
}
```

```json
{
  "task_id": "6602",
  "status": "cancelled",
  "cancelled": true,
  "remote_cancelled": false,
  "message": "任务已在本地取消并释放额度；同步生成接口没有远端取消 API，服务端可能仍在生成"
}
```

上例是 H3 Turbo 的返回形式：本地任务会立即取消，但上游同步接口没有远端取消能力。其他视频模型的返回中会包含 ComfyUI 取消状态。

---

## 计费说明

- 对话模型按实际 Token 用量和模型单价计费
- 图片、视频按应用配置价格计费；视频 `once` 类型按配置单价 × 请求时长预估
- 提交生成任务时先预占余额，任务成功后结算实际费用
- 任务失败或取消会释放对应预占额度
- 余额不足时拒绝请求
- API 密钥可独立设置额度，并统计已用和进行中预占金额

---

## 错误码

| 状态码 | 说明 |
| --- | --- |
| 400 | 请求参数、模型能力或素材组合不符合要求 |
| 401 | API 密钥无效或已过期 |
| 402 | 余额或 API 密钥额度不足 |
| 403 | 账户已被禁用，或无权访问该任务 |
| 404 | 任务不存在 |
| 413 | 请求体或上传素材过大 |
| 422 | 字段校验失败或内容未通过安全审核 |
| 429 | 请求频率超限 |
| 500 | 服务内部错误 |
| 503 | 服务不可用 |