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

# 可灵图片生成接口API 文档

本文档根据你提供的 CURL 示例整理，适用于通过 `https://api.cxsee.com` 调用图片生成任务，并通过任务查询接口获取生成结果。
提交任务 POST https://api.cxsee.com/v1/images/generations
任务查询 GET https://api.cxsee.com/v1/tasks/{task_id}

> 注意：示例中的 API Key 请勿公开暴露。文档中统一使用 `YOUR_API_KEY` 代替真实密钥。

---

# 1. 接口概览

## 图片生成流程

图片生成接口采用**异步任务模式**：

1. 调用图片生成接口提交任务；
2. 接口返回 `task_id`；
3. 使用 `task_id` 调用任务查询接口；
4. 当任务状态为 `SUCCESS` 时，从返回结果中获取图片 URL。

流程如下：

```text
POST /v1/images/generations
        ↓
返回 task_id
        ↓
GET /v1/tasks/{task_id}
        ↓
获取图片生成结果
```

---

# 2. 鉴权方式

所有接口均需要在请求头中携带 Bearer Token。

## Header

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 示例

```http
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
```

---

# 3. 创建图片生成任务

## 接口地址

```http
POST https://api.cxsee.com/v1/images/generations
```

---

## 请求 Header

| 参数 | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | API Key，格式为 `Bearer YOUR_API_KEY` |
| Content-Type | 是 | 固定为 `application/json` |

---

## 请求 Body

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名称，例如 `kling-image-v1` |
| prompt | string | 是 | 图片生成提示词 |
| size | string | 否 | 图片尺寸，例如 `1024x1024` |

---

## 请求示例

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

---

## 返回示例

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

---

## 返回字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 任务 ID |
| task_id | string | 任务 ID，用于查询任务结果 |
| object | string | 对象类型。图片生成任务最终查询结果中通常为 `image` |
| model | string | 使用的模型名称 |
| status | string | 任务状态，例如 `queued` |
| progress | number | 任务进度 |
| created_at | number | 任务创建时间，Unix 时间戳 |

---

# 4. 查询任务结果

## 接口地址

```http
GET https://api.cxsee.com/v1/tasks/{task_id}
```

其中 `{task_id}` 为创建任务时返回的 `task_id`。

---

## 请求 Header

| 参数 | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | API Key，格式为 `Bearer YOUR_API_KEY` |

---

## 请求示例

```bash
curl -X GET "https://api.cxsee.com/v1/tasks/903255642088411174" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## 返回示例：任务成功

```json
{
  "data": {
    "created_at": 1783381447,
    "data": [
      {
        "url": "https://p2-fdl.klingai.com/ksc2/xxxx.png"
      }
    ],
    "error": "",
    "id": "903255642088411174",
    "model": "kling-image-v1",
    "object": "image",
    "progress": "100%",
    "status": "SUCCESS",
    "task_id": "903255642088411174",
    "updated_at": 1783381447
  },
  "message": "",
  "success": true
}
```

---

## 返回字段说明

### 外层字段

| 字段 | 类型 | 说明 |
|---|---|---|
| success | boolean | 请求是否成功 |
| message | string | 返回消息 |
| data | object | 任务详情 |

---

### data 字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 任务 ID |
| task_id | string | 任务 ID |
| model | string | 使用的模型名称 |
| object | string | 生成对象类型，图片任务为 `image` |
| status | string | 任务状态 |
| progress | string | 任务进度，例如 `100%` |
| data | array | 生成结果列表 |
| error | string | 错误信息，成功时通常为空 |
| created_at | number | 创建时间 |
| updated_at | number | 更新时间 |

---

### data.data 字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| url | string | 生成图片的访问地址 |

---

# 5. 任务状态说明

| 状态 | 说明 |
|---|---|
| queued | 任务已提交，排队中 |
| processing | 任务处理中 |
| SUCCESS | 任务成功 |
| FAILED | 任务失败 |

> 实际状态值以接口返回为准。

---

# 6. 完整调用示例

## 第一步：提交图片生成任务

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

记录返回的：

```text
task_id = 903255642088411174
```

---

## 第二步：查询任务结果

```bash
curl -X GET "https://api.cxsee.com/v1/tasks/903255642088411174" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

当：

```json
"status": "SUCCESS"
```

并且 `data.data` 中存在 `url` 时，即可获取生成图片：

```text
https://p2-fdl.klingai.com/ksc2/xxxx.png
```

---

# 7. Python 调用示例

```python
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.cxsee.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "kling-image-v1",
    "prompt": "生成一张未来城市夜景插画",
    "size": "1024x1024"
}

# 创建图片生成任务
resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json=payload
)

result = resp.json()
print(result)

task_id = result["task_id"]

# 轮询查询任务结果
while True:
    task_resp = requests.get(
        f"{BASE_URL}/v1/tasks/{task_id}",
        headers={
            "Authorization": f"Bearer {API_KEY}"
        }
    )

task_result = task_resp.json()
    print(task_result)

data = task_result.get("data", {})
    status = data.get("status")

if status == "SUCCESS":
        images = data.get("data", [])
        if images:
            print("图片地址：", images[0]["url"])
        break

if status == "FAILED":
        print("任务失败：", data.get("error"))
        break

time.sleep(3)
```

---

# 8. JavaScript 调用示例

```javascript
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.cxsee.com";

async function createImageTask() {
  const response = await fetch(`${BASE_URL}/v1/images/generations`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "kling-image-v1",
      prompt: "生成一张未来城市夜景插画",
      size: "1024x1024"
    })
  });

return await response.json();
}

async function getTaskResult(taskId) {
  const response = await fetch(`${BASE_URL}/v1/tasks/${taskId}`, {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  });

return await response.json();
}

async function main() {
  const task = await createImageTask();
  console.log("创建任务返回：", task);

const taskId = task.task_id;

while (true) {
    const result = await getTaskResult(taskId);
    console.log("任务查询返回：", result);

const data = result.data;
    const status = data?.status;

if (status === "SUCCESS") {
      const imageUrl = data.data?.[0]?.url;
      console.log("图片地址：", imageUrl);
      break;
    }

if (status === "FAILED") {
      console.log("任务失败：", data.error);
      break;
    }

await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

main();
```

---

# 9. 注意事项

1. 图片生成是异步任务，创建任务后需要通过 `task_id` 查询结果。
2. 查询结果中的图片 URL 可能有有效期，建议获取后及时下载或转存。
3. API Key 属于敏感信息，请不要放在前端页面或公开仓库中。
4. 如果任务状态不是 `SUCCESS`，应继续轮询或根据状态处理异常。
5. 建议轮询间隔设置为 `2 ~ 5` 秒，避免过于频繁请求。
6. 创建任务返回中的 `object` 可能显示为 `video`，但最终任务查询成功后 `object` 为 `image`，实际以查询接口返回结果为准。