# Proxy

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

媒体资源访问代理。

# Proxy


## GET /api/v1/proxy/download

Proxy Download
Proxy download a file with proper headers to bypass anti-hotlinking.
Returns the file with Content-Disposition header for download.

鉴权：
- Authorization: Bearer <token>（fetch/XHR）
- ?token=<jwt>（浏览器 <a href> 原生下载无法带 Authorization）

安全措施：
- 强制登录 + 配额
- 禁止访问私有 IP 地址
- 禁止访问云服务元数据端点
- DNS 解析检查防止 DNS 重绑定攻击

资源隔离：鉴权/配额短会话；下载流期间不持有 DB 连接。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "url",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "description": "Target URL to download",
        "title": "Url"
      },
      "description": "Target URL to download"
    },
    {
      "name": "filename",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "description": "Suggested filename for download",
        "title": "Filename"
      },
      "description": "Suggested filename for download"
    },
    {
      "name": "token",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "JWT token fallback when Authorization header is unavailable",
        "title": "Token"
      },
      "description": "JWT token fallback when Authorization header is unavailable"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/proxy/stream

Proxy Stream
Proxy stream a URL to bypass CORS / anti-hotlink.
This routes the traffic through the backend with proper platform-specific headers.

鉴权：
- Authorization: Bearer <token>（fetch/XHR）
- ?token=<jwt>（原生 video/audio 标签无法自定义请求头）

安全措施：
- 强制登录
- 禁止访问私有 IP 地址 (10.x.x.x, 192.168.x.x, 127.0.0.1 等)
- 禁止访问云服务元数据端点
- DNS 解析检查防止 DNS 重绑定攻击

资源隔离：鉴权/配额短会话；流式传输期间不持有 DB 连接。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "url",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "description": "Target URL to stream",
        "title": "Url"
      },
      "description": "Target URL to stream"
    },
    {
      "name": "platform",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "description": "Platform hint for setting correct Referer",
        "title": "Platform"
      },
      "description": "Platform hint for setting correct Referer"
    },
    {
      "name": "token",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "JWT token for <video>/<audio> src (no Authorization header available)",
        "title": "Token"
      },
      "description": "JWT token for <video>/<audio> src (no Authorization header available)"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


# Components

```json
{
  "schemas": {
    "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"
    }
  }
}
```