# 智能剪辑-任务查询 API Documentation

> 通过任务 ID 查询智能剪辑任务状态与结果。任务未完成时可轮询。查询不扣费。支持 GET / POST。

## Overview

This document describes how to call the **智能剪辑-任务查询** API.

- **Model / path slug**: `smartclip/task_query`
- **Task type**: `sync` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/46`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `GET|POST https://apis.xiaobao.ink/api/smartclip/task_query`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `GET / POST`
- **Note**: This endpoint accepts both GET query parameters and POST form/JSON body.

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `task_id` | Yes | 创建智能剪辑任务时返回的任务ID |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/api/smartclip/task_query?task_id=task_xxxxxxxxxxxx&key=你的密钥
```

## Details

## 接口说明：

配合真人口播、口播混剪、新闻混剪创建接口使用。创建后用返回的 `task_id` 查询结果。任务未完成时可轮询本接口。查询不扣费。

**请求方法：**支持 `GET` 与 `POST`（表单或 JSON Body 均可传 `task_id`）。

关联创建：[真人口播](/doc/25)、[口播混剪](/doc/26)、[新闻混剪](/doc/27)

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json 或 application/x-www-form-urlencoded（POST 时） |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| task_id | 是 | string | task_xxxxxxxxxxxx | 创建接口返回的任务ID；GET 查询参数，或 POST 表单/JSON |

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| task_id | string | 任务ID |
| api_type | string | realman_broadcast / broadcast_mixcut / news_mixcut |
| type | string | 固定 app |
| call_type | string | 固定 async |
| status | string | pending / processing / completed / failed |
| progress | int | 进度 0-100 |
| video_url | string | 成片地址（本站可访问），完成时有值 |
| created_at | string | 创建时间 ISO 8601 |
| completed_at | string | 完成时间 ISO 8601 |
| result | object | 仅完成时返回；含 video_url，可能含 cover_url、duration |
| power_cost | number | 创建该任务时本平台实际扣除的点数，与请求日志点数计费一致 |
| error | object | 失败时返回 code、message |
| fail_reason | string | 失败原因 |
| local_status | int | 1处理中 2完成 3失败 |

建议提交后约 2 秒开始轮询，间隔 2～5 秒；status 为 completed / failed 时停止。

## Response Example

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "task_id": "task_xxxxxxxxxxxx",
        "api_type": "realman_broadcast",
        "type": "app",
        "call_type": "async",
        "status": "completed",
        "progress": 100,
        "video_url": "https://apis.xiaobao.ink/upload/smartclip/2026/09/19/demo.mp4",
        "created_at": "2026-08-01T10:00:00+08:00",
        "completed_at": "2026-08-01T10:01:20+08:00",
        "result": {
            "video_url": "https://apis.xiaobao.ink/upload/smartclip/2026/09/19/demo.mp4"
        },
        "fail_reason": "",
        "local_status": 2,
        "power_cost": 30
    }
}
```

## Error Codes

| HTTP 响应状态码 | 说明 |
| --- | --- |
| 200 | 查询成功 |
| 400 | 缺少 task_id 等参数错误 |
| 403 | 无权查看该任务 |
| 404 | 任务不存在 |

## Usage Flow

1. Obtain your API Key from the console
2. Call the endpoint with `key` and required parameters
3. Parse the JSON (or binary) response according to the examples above

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._