# 视频反推提示词 API Documentation

> 传入短视频分享链接或直链，反推画面、镜头与可复用的视频生成提示词。异步任务。不超过 60 秒 10 点，超过则每分钟 10 点向上取整。

## Overview

This document describes how to call the **视频反推提示词** API.

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

## 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**: `POST https://xiaoapis.com/api/video/prompt`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `POST`

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `videoUrl` | Yes | 视频分享链接或直链，兼容 url、content |
| `task_id` | No | 查询任务时填写，可选 |
| `maxDuration` | No | 可选，最大处理秒数，默认 600，最大 600 |
| `notify` | No | 可选，任务完成回调地址 |

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

### Request Example

```
POST https://xiaoapis.com/api/video/prompt
```

## Details

## 接口说明：

把短视频链接交给模型，反推出画面、镜头、光影和可复用的视频生成提示词。支持抖音、快手、小红书、微信视频号等分享链接，也支持公网视频直链。单条最长处理 10 分钟。

同一地址同时支持**创建**和**查询**。创建后立即返回 `task_id`，提示词通过 `notify` 回调，或用 `task_id` 轮询。查询不扣费。

**计费：**成功后按实际时长结算。时长不超过 60 秒扣 10 点；超过 60 秒按每分钟 10 点向上取整（61–120 秒 20 点，121–180 秒 30 点，以此类推，10 分钟 100 点）。提交时按 `maxDuration` 预扣，直链能读到时长时按该时长预扣；完成后多退少补。失败退回全部预扣。识别不到时长时按 10 点结算。

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json 或 application/x-www-form-urlencoded |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| key | 是 | string | 你的密钥 | 平台 API 密钥 |
| videoUrl | 创建时必填 | string | https://v.douyin.com/xxxx | 分享链接、带链接的口令，或视频直链。兼容 url、content、link |
| maxDuration | 否 | int | 180 | 最多处理多少秒。默认 600，最大 600。预扣按这个上限计算 |
| notify | 否 | string | https://你的域名/callback | 完成后 POST JSON。兼容 callbackUrl、callBackUrl |
| task_id | 查询时必填 | string | vp_xxx | 创建返回的任务号。兼容 taskId。只传任务号时按查询处理 |
| action | 否 | string | query | create（默认）或 query |

只接受 POST。表单或 JSON 均可，参数放在请求体里。

## 创建返回说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 200 表示提交成功 |
| msg | string | 状态信息 |
| data.task_id | string | 任务号 |
| data.status | int | 0 处理中，1 成功，2 失败 |
| data.schedule | string | PROCESSING 处理中，SUCCESS 成功，FAIL 失败 |
| data.max_duration | int | 本次最长处理秒数 |
| data.power_cost | number | 本次预扣点数。完成后可能退回差额 |
| data.power_prepaid | number | 预扣点数 |

## 任务查询说明：

查询不扣费。建议间隔 3～5 秒轮询，直到 status 为 1 或 2。

```
POST /api/video/prompt
{"key":"你的密钥","action":"query","task_id":"vp_xxx"}
```

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| data.status | int | 0 处理中 / 1 成功 / 2 失败 |
| data.content | string | 反推提示词。成功时有值 |
| data.duration | int | 识别到的视频秒数。识别不到为 0，此时按 10 点结算 |
| data.power_cost | number | 处理中是预扣点数；结束后是实际扣点 |
| data.fail_reason | string | 失败原因 |

## 回调 notify 说明：

任务进入终态后 POST JSON，只推一次。

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 200 成功，400 失败 |
| msg | string | success 或失败原因 |
| data.task_id | string | 任务号 |
| data.content | string | 反推提示词 |
| data.duration | int | 视频秒数 |
| data.power_cost | number | 实际扣除点数 |
| data.fail_reason | string | 失败原因 |

## Response Example

```json
{
    "code": 200,
    "msg": "任务创建成功",
    "data": {
        "task_id": "vp_a1b2c3d4e5f67890",
        "status": 0,
        "schedule": "PROCESSING",
        "max_duration": 600,
        "power_cost": 100,
        "power_prepaid": 100,
        "billing": "已预扣。完成后按实际时长结算：不超过 60 秒 10 点，超过则每分钟 10 点向上取整，差额退回"
    }
}
```

## Error Codes

| 业务码 | 说明 |
| --- | --- |
| 200 | 创建成功或查询成功 |
| 400 | 参数错误、点数不足，或任务失败 |
| 403 | 认证失败，请检查 key |
| 500 | 服务暂时繁忙。此类错误不扣费 |

## Usage Flow

1. **Create Task**: Call this API with your `key` and required parameters
2. **Get Task ID**: Read the task id from the response
3. **Wait for Results**: Use the notify/callback URL if provided, or poll the related query endpoint
4. **Get Results**: When the task succeeds, read result URLs / payload from the response

---

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