# 任务查询

> 查询 AI MediaKit 系列任务的状态与结果：进行中、成功（成片链接）、失败（错误原因）。

AI MediaKit 系列所有能力共用同一个任务查询接口。用提交时返回的 `task_id` 轮询，建议每 5–15 秒一次。

```
GET /api/aimediakit/api/v1/tasks/{task_id}
```

```bash cURL
curl "https://api.looprouter.com/api/aimediakit/api/v1/tasks/vg_9f8c1e2b7a6d4f30" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY"
```

## 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `success` | bool | 本次查询请求是否成功（不代表任务成败） |
| `task_id` | string | 任务 ID |
| `task_type` | string | 能力标识：`video-frame-interpolation` / `erase-video-subtitle-pro` / `enhance-video` / `enhance-video-generative` |
| `status` | string | 任务状态：`running`（进行中）/ `completed`（成功）/ `failed`（失败） |
| `result` | object | 任务成功时的结果，见下；其余状态不返回 |
| `error` | object | 任务失败时的错误信息，见下；其余状态不返回 |
| `created_at` | number | 任务创建时间（Unix 秒） |
| `finished_at` | number | 任务结束时间（Unix 秒），未结束不返回 |
| `request_id` | string | 本次请求 ID |

### `result` 对象（任务成功时）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `video_url` | string | 成片下载链接（**临时链接，约 2 小时后失效**，请尽快下载） |
| `resolution` | string | 实际输出分辨率档位（`240p`–`8k`）。插帧 / 画质增强返回；字幕擦除不返回 |
| `duration` | number | 成片时长（秒） |
| `fps` | number | 实际输出帧率。插帧 / 画质增强返回；字幕擦除不返回 |
| `tool_version` | string | 仅画质增强标准版 / 专业版返回（`standard` / `professional`） |

### `error` 对象（任务失败时）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 固定 `TaskFailed` |
| `type` | string | 固定 `TaskError` |
| `message` | string | 失败原因说明 |

<Note>
计费按**实际用量后付费**：任务成功后才按实际输出计费，任务失败**不收费**。
</Note>

## 响应示例

### 进行中

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "task_type": "enhance-video",
  "status": "running",
  "created_at": 1756699200,
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

### 成功

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "task_type": "enhance-video",
  "status": "completed",
  "result": {
    "video_url": "https://…/out.mp4?…",
    "resolution": "1080p",
    "duration": 12.5,
    "fps": 30,
    "tool_version": "professional"
  },
  "created_at": 1756699200,
  "finished_at": 1756699320,
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

### 失败

```json
{
  "success": true,
  "task_id": "vg_9f8c1e2b7a6d4f30",
  "task_type": "erase-video-subtitle-pro",
  "status": "failed",
  "error": {
    "code": "TaskFailed",
    "type": "TaskError",
    "message": "source video download failed"
  },
  "created_at": 1756699200,
  "finished_at": 1756699280,
  "request_id": "b1e6c2f0-3a4d-4e5f-8a90-1234567890ab"
}
```

## 完整调用流程（Python）

提交任务 → 轮询直到完成 → 下载成片，切换能力只需改提交接口与参数：

```python Python
import time
import requests

BASE = "https://api.looprouter.com/api/aimediakit"
HEADERS = {"Authorization": "Bearer sk-你的APIKey"}

# 1. 提交任务（以智能插帧为例）
submit = requests.post(
    f"{BASE}/api/v1/tools/video-frame-interpolation",
    headers=HEADERS,
    json={"video_url": "https://example.com/source.mp4", "fps": 60},
)
submit.raise_for_status()
task_id = submit.json()["task_id"]
print("task_id:", task_id)

# 2. 轮询任务状态（建议每 5–15 秒一次）
while True:
    time.sleep(10)
    task = requests.get(f"{BASE}/api/v1/tasks/{task_id}", headers=HEADERS).json()
    print(task["status"])
    if task["status"] in ("completed", "failed"):
        break

if task["status"] == "failed":
    raise RuntimeError(task["error"]["message"])

# 3. 下载成片（临时链接约 2 小时失效，下载无需 Authorization）
video_url = task["result"]["video_url"]
data = requests.get(video_url).content       # 注意：不要带 HEADERS
with open("result.mp4", "wb") as f:
    f.write(data)
print("已保存 result.mp4，时长（秒）：", task["result"]["duration"])
```

<Warning>
成片 `video_url` 为**临时链接**，约 **2 小时**后失效，请尽快下载并转存到你自己的存储。
</Warning>