# Download

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

媒体下载和文件获取。

# Download


## DELETE /api/v1/download/cache/clear

Clear Cache
清空所有缓存

需要管理员权限（当前为演示模式）

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


## GET /api/v1/download/cache/stats

Get Cache Stats
获取缓存统计信息（无需认证）

返回缓存命中率、内存使用情况等统计数据

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


## POST /api/v1/download/extract-audio

Extract Audio From Video
从视频URL提取音频

从视频URL下载并提取音频，返回音频文件URL

返回码说明：
- 200: 提取成功
- 202: 正在处理中，前端应每隔 retry_after 秒轮询本接口直至完成
- 400: 请求参数错误
- 500: 服务器内部错误

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


## POST /api/v1/download/extract-bgm

Extract Bgm
提取背景音乐

从音频URL中提取背景音乐

返回码说明：
- 200: 提取成功
- 202: 正在处理中，前端应每隔 retry_after 秒轮询本接口直至完成
- 400: 请求参数错误
- 500: 服务器内部错误

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


## POST /api/v1/download/extract-text

Extract Text
提取音频文案（口播文案）

从音频URL中提取口播文案文本内容

返回码说明：
- 200: 提取成功，返回文案内容
- 202: 正在处理中，前端应每隔 retry_after 秒轮询本接口直至完成
- 400: 请求参数错误
- 500: 服务器内部错误

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


## GET /api/v1/download/media/{path}

Download Media File
下载媒体文件代理端点

用于代理 MinIO 中的媒体文件，支持视频、音频等文件的下载
支持 Range 请求（视频拖动播放）

Args:
    path: 媒体文件路径，如 videos/filename.mp4, audios/filename.mp3
    download: true 时用 Content-Disposition: attachment（移动端「另存为」）

```json
{
  "parameters": [
    {
      "name": "path",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Path"
      }
    },
    {
      "name": "download",
      "in": "query",
      "required": false,
      "schema": {
        "type": "boolean",
        "default": false,
        "title": "Download"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


# Components

```json
{
  "schemas": {
    "ExtractMediaRequest": {
      "properties": {
        "url": {
          "type": "string",
          "title": "Url",
          "description": "媒体 URL：平台分享链，或 resolve 得到的音频/视频直链。抖音等 CDN 直链易因预览/防盗链 403，建议同时传 source_url。"
        },
        "source_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source Url",
          "description": "平台原始分享/详情页 URL（如 https://v.douyin.com/xxx/）。文案/BGM 提取时用于原子「重解析新鲜音轨 + 中转到对象存储」，避免把已过期/被预览占用的 CDN 直链交给 Infer。"
        },
        "download_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Download Type",
          "description": "可选下载类型标记（前端兼容字段，后端可忽略）"
        },
        "extract_bgm": {
          "type": "boolean",
          "title": "Extract Bgm",
          "description": "是否提取背景音乐（默认不提取）",
          "default": false
        },
        "extract_transcript": {
          "type": "boolean",
          "title": "Extract Transcript",
          "description": "是否提取口播文案（默认不提取）",
          "default": false
        }
      },
      "type": "object",
      "required": [
        "url"
      ],
      "title": "ExtractMediaRequest",
      "description": "提取媒体信息请求"
    },
    "HTTPValidationError": {
      "properties": {
        "detail": {
          "items": {
            "$ref": "#/components/schemas/ValidationError"
          },
          "type": "array",
          "title": "Detail"
        }
      },
      "type": "object",
      "title": "HTTPValidationError"
    },
    "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"
    }
  },
  "securitySchemes": {
    "HTTPBearer": {
      "type": "http",
      "scheme": "bearer"
    }
  }
}
```