> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hingnet.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 任务查询

> 通用任务查询接口说明；支持 task_id 和 external_task_id

所有可灵的异步任务均可通过对应的查询接口获取任务状态和结果。

任务状态

| 状态           | 含义  | 说明                        |
| ------------ | --- | ------------------------- |
| `submitted`  | 已提交 | 任务已进入队列                   |
| `processing` | 处理中 | 任务正在生成                    |
| `succeed`    | 成功  | 任务完成，可获取结果                |
| `failed`     | 失败  | 任务失败，查看 `task_status_msg` |

任务ID说明

* **task\_id**：上游原始任务 ID（由可灵官方生成）
* **platform\_id**：One-Hub 平台统一追踪 ID，格式为 `video_<ULID>`（视频）或 `image_<ULID>`（图像）
* **external\_task\_id**：用户自定义的任务ID，可用于幂等控制和业务关联

查询接口支持以上任一 ID 进行查询。

通用响应字段

| 字段                           | 说明                                               |
| ---------------------------- | ------------------------------------------------ |
| `task_id`                    | 上游原始任务 ID                                        |
| `platform_id`                | One-Hub 平台统一追踪 ID                                |
| `task_status`                | 任务状态：`submitted`/`processing`/`succeed`/`failed` |
| `task_status_msg`            | 失败原因（仅失败时返回）                                     |
| `task_info.external_task_id` | 回显创建任务时传入的自定义ID                                  |
| `task_result`                | 任务结果（成功时返回）                                      |
| `watermark_info`             | 水印回显（创建任务时启用后返回）                                 |
| `final_unit_deduction`       | 实际扣减积分（成功后回写）                                    |
| `created_at`/`updated_at`    | 毫秒级时间戳                                           |

计费字段

* 响应包含 `final_unit_deduction` 时，按积分计费：
  * 视频：1 积分 = 1 元
  * 图像：1 积分 = 0.025 元
* 若未返回 `final_unit_deduction`，不再回退模型默认价格，任务不计费。

## 视频生成任务查询

### 文生视频

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/videos/text2video/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/videos/text2video?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

### 图生视频

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/videos/image2video/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/videos/image2video?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

### Omni 视频

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/videos/omni-video/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/videos/omni-video?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

### 多图参考生视频

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/videos/multi-image2video/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/videos/multi-image2video?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

## 图像生成任务查询

### 单图生成

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/images/generations/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/images/generations?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

### Omni 图像

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/images/omni-image/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/images/omni-image?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

### 多图参考生图

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/images/multi-image2image/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/images/multi-image2image?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

## 多模态编辑任务查询

```bash theme={null}
# 查询单个任务
curl "https://models.hingnet.com.cn/kling/v1/videos/multi-elements/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN"

# 查询任务列表
curl "https://models.hingnet.com.cn/kling/v1/videos/multi-elements?pageNum=1&pageSize=30" \
  -H "Authorization: Bearer $TOKEN"
```

## 分页参数

| 参数         | 类型  | 默认值 | 范围         | 说明   |
| ---------- | --- | --- | ---------- | ---- |
| `pageNum`  | int | 1   | \[1, 1000] | 页码   |
| `pageSize` | int | 30  | \[1, 500]  | 每页数量 |

## 视频任务成功响应示例

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "req_...",
  "data": {
    "task_id": "task_01JGHS...",
    "task_status": "succeed",
    "task_info": {
      "external_task_id": "my-custom-id-123"
    },
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "7",
    "task_result": {
      "videos": [
        {
          "id": "vid_abc123",
          "url": "https://cdn.example.com/generated-video.mp4",
          "duration": "5"
        }
      ]
    },
    "created_at": 1735558800000,
    "updated_at": 1735559100000
  }
}
```

## 图像任务成功响应示例

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "req_...",
  "data": {
    "task_id": "task_01JGHT...",
    "task_status": "succeed",
    "watermark_info": {
      "enabled": true
    },
    "final_unit_deduction": "4",
    "task_result": {
      "images": [
        {"index": 0, "url": "https://cdn.example.com/image-0.jpg"},
        {"index": 1, "url": "https://cdn.example.com/image-1.jpg"}
      ]
    },
    "created_at": 1735558800000,
    "updated_at": 1735559000000
  }
}
```

## 任务失败响应示例

```json theme={null}
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "task_01JGHU...",
    "task_status": "failed",
    "task_status_msg": "Content moderation failed",
    "created_at": 1735558800000,
    "updated_at": 1735558900000
  }
}
```