# GPU Infer

Base URL `https://sniphunter.com/ai`

视频超分、抠像与推理任务。

# Video


## POST /api/v1/video/bg-remove

Bg Remove


```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VideoBgRemoveRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoEnhanceResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/video/enhance

Enhance


```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VideoEnhanceRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoEnhanceResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/video/enhance/status

Enhance Status
探测当前设备与可用引擎。

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## POST /api/v1/video/subtitle/detect

Detect Subtitle
自动检测字幕条带区域（引擎 PP-OCRv5 采样检测，聚合文本框）。

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SubtitleDetectRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubtitleDetectResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/video/subtitle/remove

Remove Subtitle
视频去字幕（同步兼容端点）。

内部与 POST /tasks 走同一任务管线（时长门限/串行调度/真实进度一致），
等待任务完成后一次性返回。新接入方请使用异步任务端点。

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SubtitleRemoveRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubtitleRemoveResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/video/subtitle/status

Get Service Status
去字幕服务状态：VSR 引擎(in-process) 权重就绪情况。

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## POST /api/v1/video/subtitle/tasks

Submit Subtitle Task
提交去字幕异步任务：立即返回 task_id，GET /tasks/{task_id} 轮询真实进度。

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SubtitleRemoveRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubtitleTaskSubmitResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/video/subtitle/tasks/{task_id}

Get Subtitle Task
查询去字幕任务：真实进度 / 排队位置 / 时长 / 预估耗时 / 结果。

```json
{
  "parameters": [
    {
      "name": "task_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Task Id"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubtitleTaskStatusResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/video/tasks

Submit Unified Video Task
提交视频异步任务（超分 / 增强 / 抠图）。

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VideoTaskSubmitRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoAsyncTaskSubmitResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/video/tasks/{task_id}

Get Unified Video Task
查询统一视频任务状态（任意 kind）。

```json
{
  "parameters": [
    {
      "name": "task_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Task Id"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoAsyncTaskStatusResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/video/upscale

Upscale


```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/VideoUpscaleRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoEnhanceResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/video/watermark/detect

Detect Watermark
水印自动检测（同步）。

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/WatermarkDetectRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WatermarkDetectResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/video/watermark/remove

Remove Watermark
视频去水印（同步兼容端点）。
内部与 POST /tasks 同一管线，等待完成后一次性返回。

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/WatermarkRemoveRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/WatermarkRemoveResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/video/watermark/status

Get Service Status
获取水印去除服务状态。

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## POST /api/v1/video/watermark/tasks

Submit Watermark Task
提交视频去水印异步任务。

```json
{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/WatermarkRemoveRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoAsyncTaskSubmitResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/video/watermark/tasks/{task_id}

Get Watermark Task
查询去水印任务状态。

```json
{
  "parameters": [
    {
      "name": "task_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Task Id"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/VideoAsyncTaskStatusResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


# Health


## GET /

Root


```json
{
  "security": [],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    }
  }
}
```


## GET /api/v1/health

Health Check
存活 / 浅层健康探针。

- 默认：进程可响应即 healthy（liveness）
- INFER_REQUIRE_CUDA=1：额外做 CUDA 张量探针；失败返回 status=unhealthy
  （Docker healthcheck 可据此标记 unhealthy；真正自愈靠进程 exit + restart）
深度就绪请用 /ready。

```json
{
  "security": [],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HealthResponse"
          }
        }
      }
    }
  }
}
```


# ready


## GET /api/v1/ready

Readiness Check
就绪检查：对象存储 + 内存 + CUDA 信息 + 关键权重（权重缺失为 degraded 但仍 ready，
仅 storage/memory 失败时 ready=false，避免无存储时仍接写任务）。

```json
{
  "security": [],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReadyResponse"
          }
        }
      }
    }
  }
}
```


# status


## GET /api/v1/status/models

Model Status
模型 / GPU 槽位状态（含懒加载注册表）

```json
{
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ModelStatusResponse"
          }
        }
      }
    }
  }
}
```


# Components

```json
{
  "schemas": {
    "HTTPValidationError": {
      "properties": {
        "detail": {
          "items": {
            "$ref": "#/components/schemas/ValidationError"
          },
          "type": "array",
          "title": "Detail"
        }
      },
      "type": "object",
      "title": "HTTPValidationError"
    },
    "HealthResponse": {
      "properties": {
        "status": {
          "type": "string",
          "title": "Status",
          "description": "服务状态"
        },
        "service": {
          "type": "string",
          "title": "Service",
          "description": "服务名称"
        },
        "version": {
          "type": "string",
          "title": "Version",
          "description": "服务版本"
        }
      },
      "type": "object",
      "required": [
        "status",
        "service",
        "version"
      ],
      "title": "HealthResponse",
      "description": "健康检查响应"
    },
    "ModelStatusResponse": {
      "properties": {
        "loaded_models": {
          "items": {},
          "type": "array",
          "title": "Loaded Models",
          "description": "已加载的模型列表"
        },
        "estimated_usage_mb": {
          "type": "integer",
          "title": "Estimated Usage Mb",
          "description": "估算内存使用 (MB)",
          "default": 0
        },
        "memory_budget_mb": {
          "type": "integer",
          "title": "Memory Budget Mb",
          "description": "内存预算 (MB)",
          "default": 0
        },
        "system_memory": {
          "additionalProperties": true,
          "type": "object",
          "title": "System Memory",
          "description": "系统内存状态"
        }
      },
      "type": "object",
      "title": "ModelStatusResponse",
      "description": "模型状态响应"
    },
    "ReadyResponse": {
      "properties": {
        "ready": {
          "type": "boolean",
          "title": "Ready",
          "description": "是否就绪"
        },
        "checks": {
          "additionalProperties": true,
          "type": "object",
          "title": "Checks",
          "description": "各项检查结果"
        }
      },
      "type": "object",
      "required": [
        "ready"
      ],
      "title": "ReadyResponse",
      "description": "就绪检查响应"
    },
    "SubtitleDetectRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "SubtitleDetectRequest",
      "description": "字幕区域自动检测请求"
    },
    "SubtitleDetectResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态"
        },
        "detected_region": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/SubtitleRegion"
            },
            {
              "type": "null"
            }
          ],
          "description": "推荐的字幕条带区域"
        },
        "preview_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Preview Url",
          "description": "预览图 URL"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error",
          "description": "错误信息"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "SubtitleDetectResponse",
      "description": "字幕区域自动检测响应"
    },
    "SubtitleRegion": {
      "properties": {
        "x": {
          "type": "integer",
          "minimum": 0.0,
          "title": "X",
          "description": "左上角 X"
        },
        "y": {
          "type": "integer",
          "minimum": 0.0,
          "title": "Y",
          "description": "左上角 Y"
        },
        "width": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Width",
          "description": "宽度"
        },
        "height": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Height",
          "description": "高度"
        }
      },
      "type": "object",
      "required": [
        "x",
        "y",
        "width",
        "height"
      ],
      "title": "SubtitleRegion",
      "description": "字幕区域（像素坐标）"
    },
    "SubtitleRemoveRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Task Id",
          "description": "可选任务关联 ID；缺省服务端生成"
        },
        "region": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/SubtitleRegion"
            },
            {
              "type": "null"
            }
          ],
          "description": "显式字幕区域（像素）。传入后整框全片擦除，不跑 OCR；省略则 auto 检测"
        },
        "mode": {
          "type": "string",
          "enum": [
            "standard",
            "high",
            "fast"
          ],
          "title": "Mode",
          "description": "产品档位（均走 VSR）：fast=OpenCV | standard=LaMa | high=ProPainter。引擎调参与算法由服务内置推导。",
          "default": "standard"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp4"
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "SubtitleRemoveRequest",
      "description": "去字幕请求\n\n区域来源二选一：\n  - 传 region（像素坐标）→ 整框矩形 mask 全片擦除该区域（不依赖 OCR）\n  - 不传 region → auto 自动检测字幕主带 + OCR 定位有字幕帧"
    },
    "SubtitleRemoveResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: processing/completed/failed"
        },
        "result": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Result",
          "description": "处理结果"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error",
          "description": "错误信息"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "SubtitleRemoveResponse",
      "description": "去字幕响应"
    },
    "SubtitleTaskStatusResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: queued/processing/completed/failed"
        },
        "progress": {
          "type": "number",
          "title": "Progress",
          "description": "真实进度 0~100（下载/引擎/上传全链路）",
          "default": 0
        },
        "current_step": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current Step",
          "description": "当前步骤"
        },
        "queue_position": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Queue Position",
          "description": "排队位置（仅 queued）"
        },
        "video_duration": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Video Duration",
          "description": "输入视频时长（秒）"
        },
        "estimated_time_seconds": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Estimated Time Seconds",
          "description": "预估处理耗时（秒）"
        },
        "result": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Result",
          "description": "处理结果（completed 时）"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error",
          "description": "错误信息（failed 时）"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "SubtitleTaskStatusResponse",
      "description": "去字幕异步任务状态"
    },
    "SubtitleTaskSubmitResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: queued/processing"
        },
        "queue_position": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Queue Position",
          "description": "排队位置（1=下一个执行）"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "SubtitleTaskSubmitResponse",
      "description": "去字幕异步任务提交响应"
    },
    "ValidationError": {
      "properties": {
        "loc": {
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "type": "array",
          "title": "Location"
        },
        "msg": {
          "type": "string",
          "title": "Message"
        },
        "type": {
          "type": "string",
          "title": "Error Type"
        }
      },
      "type": "object",
      "required": [
        "loc",
        "msg",
        "type"
      ],
      "title": "ValidationError"
    },
    "VideoAsyncTaskStatusResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "kind": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Kind",
          "description": "任务类型"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: queued/processing/completed/failed"
        },
        "progress": {
          "type": "number",
          "title": "Progress",
          "description": "进度 0~100",
          "default": 0
        },
        "current_step": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current Step",
          "description": "当前步骤"
        },
        "queue_position": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Queue Position",
          "description": "排队位置（仅 queued）"
        },
        "video_duration": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Video Duration",
          "description": "输入视频时长（秒）"
        },
        "estimated_time_seconds": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Estimated Time Seconds",
          "description": "预估耗时（秒）"
        },
        "result": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Result",
          "description": "处理结果（completed 时）"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error",
          "description": "错误信息（failed 时）"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "VideoAsyncTaskStatusResponse",
      "description": "通用视频异步任务状态"
    },
    "VideoAsyncTaskSubmitResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: queued/processing"
        },
        "kind": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Kind",
          "description": "任务类型"
        },
        "queue_position": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Queue Position",
          "description": "排队位置（1=下一个执行）"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "VideoAsyncTaskSubmitResponse",
      "description": "通用视频异步任务提交响应"
    },
    "VideoBgRemoveRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Task Id",
          "description": "可选任务关联 ID；缺省服务端生成"
        },
        "bg_color": {
          "type": "string",
          "title": "Bg Color",
          "description": "背景填充色（hex），默认绿幕",
          "default": "#00FF00"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp4"
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "VideoBgRemoveRequest",
      "description": "视频抠图（背景移除）请求"
    },
    "VideoEnhanceRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Task Id",
          "description": "可选任务关联 ID；缺省服务端生成"
        },
        "scale": {
          "type": "integer",
          "maximum": 4.0,
          "minimum": 1.0,
          "title": "Scale",
          "description": "放大倍数（1 = 不放大）",
          "default": 1
        },
        "face_enhance": {
          "type": "boolean",
          "title": "Face Enhance",
          "description": "人脸修复",
          "default": true
        },
        "denoise": {
          "type": "boolean",
          "title": "Denoise",
          "description": "降噪锐化",
          "default": true
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp4"
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "VideoEnhanceRequest",
      "description": "视频 AI 增强请求"
    },
    "VideoEnhanceResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: completed/failed"
        },
        "result": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Result",
          "description": "处理结果"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error",
          "description": "错误信息"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "VideoEnhanceResponse",
      "description": "统一响应"
    },
    "VideoTaskSubmitRequest": {
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "subtitle",
            "watermark",
            "upscale",
            "bg-remove",
            "bg_remove"
          ],
          "title": "Kind",
          "description": "任务类型"
        },
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Task Id",
          "description": "可选任务关联 ID；缺省服务端生成"
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp4"
        },
        "region": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/SubtitleRegion"
            },
            {
              "type": "null"
            }
          ],
          "description": "去字幕显式区域（像素）"
        },
        "mode": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "standard",
                "high",
                "fast"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Mode",
          "description": "去字幕档位",
          "default": "standard"
        },
        "regions": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/components/schemas/WatermarkRegion"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Regions",
          "description": "去水印手动区域"
        },
        "auto_detect": {
          "type": "boolean",
          "title": "Auto Detect",
          "description": "去水印自动检测",
          "default": true
        },
        "detection_sensitivity": {
          "type": "string",
          "title": "Detection Sensitivity",
          "description": "去水印检测敏感度",
          "default": "medium"
        },
        "quality": {
          "type": "string",
          "title": "Quality",
          "description": "去水印质量 fast/medium/high",
          "default": "medium"
        },
        "processing_height": {
          "type": "integer",
          "maximum": 1080.0,
          "minimum": 240.0,
          "title": "Processing Height",
          "description": "去水印处理高度",
          "default": 720
        },
        "scale": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 4.0,
              "minimum": 1.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Scale",
          "description": "超分/增强放大倍数"
        },
        "face_enhance": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Face Enhance",
          "description": "超分/增强人脸修复"
        },
        "denoise": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Denoise",
          "description": "增强降噪"
        },
        "bg_color": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bg Color",
          "description": "抠图背景色 hex"
        }
      },
      "type": "object",
      "required": [
        "kind",
        "video_url"
      ],
      "title": "VideoTaskSubmitRequest",
      "description": "统一视频异步任务提交。\n\nkind: subtitle | watermark | upscale | bg-remove\n公共字段 video_url / task_id / output_format；其余按 kind 选用。\n生产去字幕/去水印走 media；本进程代码保留。"
    },
    "VideoUpscaleRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Task Id",
          "description": "可选任务关联 ID；缺省服务端生成"
        },
        "scale": {
          "type": "integer",
          "maximum": 4.0,
          "minimum": 2.0,
          "title": "Scale",
          "description": "放大倍数 2/3/4",
          "default": 2
        },
        "face_enhance": {
          "type": "boolean",
          "title": "Face Enhance",
          "description": "是否启用人脸修复（GFPGAN）",
          "default": false
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp4"
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "VideoUpscaleRequest",
      "description": "视频超分请求"
    },
    "WatermarkDetectRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        },
        "sensitivity": {
          "type": "string",
          "title": "Sensitivity",
          "description": "检测敏感度: low/medium/high",
          "default": "medium"
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "WatermarkDetectRequest",
      "description": "水印检测请求"
    },
    "WatermarkDetectResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态"
        },
        "detected_regions": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/components/schemas/WatermarkRegion"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Detected Regions",
          "description": "检测到的水印区域"
        },
        "preview_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Preview Url",
          "description": "检测结果预览图 URL"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error",
          "description": "错误信息"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "WatermarkDetectResponse",
      "description": "水印检测响应"
    },
    "WatermarkRegion": {
      "properties": {
        "x": {
          "type": "integer",
          "title": "X",
          "description": "左上角 X 坐标"
        },
        "y": {
          "type": "integer",
          "title": "Y",
          "description": "左上角 Y 坐标"
        },
        "width": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Width",
          "description": "宽度"
        },
        "height": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Height",
          "description": "高度"
        }
      },
      "type": "object",
      "required": [
        "x",
        "y",
        "width",
        "height"
      ],
      "title": "WatermarkRegion",
      "description": "水印区域"
    },
    "WatermarkRemoveRequest": {
      "properties": {
        "video_url": {
          "type": "string",
          "title": "Video Url",
          "description": "视频文件 URL"
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Task Id",
          "description": "可选任务关联 ID；缺省服务端生成"
        },
        "regions": {
          "anyOf": [
            {
              "items": {
                "$ref": "#/components/schemas/WatermarkRegion"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "title": "Regions",
          "description": "手动指定的水印区域列表。如果为空，将自动检测"
        },
        "auto_detect": {
          "type": "boolean",
          "title": "Auto Detect",
          "description": "是否自动检测水印（当 regions 为空时生效）",
          "default": true
        },
        "detection_sensitivity": {
          "type": "string",
          "title": "Detection Sensitivity",
          "description": "自动检测敏感度: low/medium/high",
          "default": "medium"
        },
        "quality": {
          "type": "string",
          "title": "Quality",
          "description": "处理质量/算法：fast=OpenCV | medium=LaMa | high=ProPainter",
          "default": "medium"
        },
        "processing_height": {
          "type": "integer",
          "maximum": 1080.0,
          "minimum": 240.0,
          "title": "Processing Height",
          "description": "处理高度（像素）。默认 720；越高画质越好、越吃显存",
          "default": 720
        },
        "output_format": {
          "type": "string",
          "title": "Output Format",
          "description": "输出格式",
          "default": "mp4"
        },
        "output_quality": {
          "type": "integer",
          "maximum": 100.0,
          "minimum": 1.0,
          "title": "Output Quality",
          "description": "输出质量 1-100",
          "default": 80
        }
      },
      "type": "object",
      "required": [
        "video_url"
      ],
      "title": "WatermarkRemoveRequest",
      "description": "水印去除请求"
    },
    "WatermarkRemoveResponse": {
      "properties": {
        "task_id": {
          "type": "string",
          "title": "Task Id",
          "description": "任务 ID"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: processing/completed/failed"
        },
        "result": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Result",
          "description": "处理结果"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error",
          "description": "错误信息"
        }
      },
      "type": "object",
      "required": [
        "task_id",
        "status"
      ],
      "title": "WatermarkRemoveResponse",
      "description": "水印去除响应"
    }
  },
  "securitySchemes": {
    "ServiceApiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "服务间密钥，鉴权是否启用由部署配置决定。"
    }
  }
}
```