可灵（Kling）绘画 - 数字先锋API文档

# 可灵绘画与任务查询 API 文档（Kling）

体验网址：https://try.cxsee.com/image/kling
## 1. 概述

本接口用于提交图片生成任务（异步），提交后立即返回 `task_id`，再通过任务查询接口轮询任务状态，任务成功后可获取图片 URL。任务查询均是免费
图像生成涉及模型 kling-v1 kling-v1-5 kling-v2 kling-v2-1

- 提交接口：`POST /v1/images/generations`
- 查询接口：`GET /v1/tasks/{task_id}`（建议你服务端按此路由提供；若现有路由不同，替换即可）

---

## 2. 鉴权

所有接口均需在 Header 中携带 Bearer Token：

```http
Authorization: Bearer sk-xxxxxxxx
Content-Type: application/json
```

---

## 3. 提交图片生成任务

### 3.1 请求

**URL**
```http
POST /v1/images/generations
```

**Body 参数**

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名，如 `kling-v1` |
| prompt | string | 是 | 生图提示词 |
| size | string | 否 | 图片尺寸，如 `1024x1024` |

**示例请求**
```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v1",
    "prompt": "生成一张未来城市夜景插画",
    "size": "1024x1024"
  }'
```

---

### 3.2 响应（提交成功，任务进入排队）

```json
{
  "id": "868599031210463327",
  "task_id": "868599031210463327",
  "object": "video",
  "model": "kling-v1",
  "status": "queued",
  "progress": 0,
  "created_at": 1775118667
}
```

> 说明：
> - `task_id`：后续查询任务状态的唯一 ID
> - `status=queued`：任务已创建，等待执行
> - `progress`：进度（0~100）

---

## 4. 查询任务状态

### 4.1 请求

**URL**
```http
GET /v1/tasks/{task_id}
```

**示例**
```bash
curl -X GET "https://api.cxsee.com/v1/tasks/868599031210463327" \
  -H "Authorization: Bearer sk-xxxx"
```

---

### 4.2 响应（成功示例）

```json
{
  "id": 147,
  "task_id": "868599031210463327",
  "external_task_id": "868599031210463327",
  "platform": "kling",
  "user_id": 1,
  "quota": 40000,
  "action": "generate",
  "status": "SUCCESS",
  "progress": "100%",
  "submit_time": 1775118667,
  "finish_time": 1775118692,
  "properties": {
    "upstream_model_name": "kling-v1",
    "origin_model_name": "kling-v1",
    "query_action": "image",
    "submit_path": "/v1/images/generations"
  },
  "data": {
    "code": 0,
    "data": {
      "task_id": "868599031210463327",
      "task_status": "succeed",
      "task_result": {
        "images": [
          {
            "url": "https://...png"
          }
        ]
      }
    },
    "message": "成功",
    "request_id": "868599031210463327"
  }
}
```

---

## 5. 状态说明

### 平台任务状态（建议对外统一）
| status | 含义 |
|---|---|
| queued / PENDING | 已提交，排队中 |
| running / PROCESSING | 生成中 |
| SUCCESS | 生成成功 |
| FAIL | 生成失败 |

### 成功判定
- 任务主状态：`status = SUCCESS`
- 上游状态：`data.data.task_status = succeed`
- 图片结果：`data.data.task_result.images[].url` 存在

---

## 6. 错误码建议（可对外规范）

| code | 含义 |
|---|---|
| 400 | 参数错误（如缺少 prompt/model） |
| 401 | 未授权/Token 无效 |
| 403 | 无权限使用该模型 |
| 429 | 请求频率超限 |
| 500 | 服务内部错误 |
| 502/504 | 上游模型服务异常/超时 |

---

## 7. 计费说明（按你日志）

从日志可见本次 `kling-v1` 图片生成走**固定价预扣费**：
- `model_price = 0.08`
- `group_ratio = 1`
- `quota = 40000`（按系统 QuotaPerUnit 换算）
- 日志标记：`async_preconsume=true`, `billing_phase=submit_preconsume`

> “图片异步任务在提交时按固定价预扣额度；最终以系统结算策略为准。”

---

## 8. 客户端轮询建议

- 提交成功后，每 `2~3 秒`查询一次任务状态
- 超时时间建议 `2~5 分钟`
- 若 `SUCCESS`，读取图片 URL 展示/下载
- 若 `FAIL`，展示失败原因（若返回 `fail_reason`）

---