# Extraction

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

视频、音频和图文内容提取。

# Extraction


## POST /api/v1/extraction/analyze

分析 URL（纯素材解析，不下载不上传）
分析 URL 并解析素材元数据与直链。

**仅数据提取**：返回平台 video/audio/cover 直链与标题等元数据。
**不会**下载媒体文件、**不会**上传到对象存储、**不会**做 BGM/ASR。
需要落盘/转存、口播文案、人声分离请走独立原子能力。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ExtractionAnalyzeRequest"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExtractionResultResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/extraction/history

获取提取历史
获取用户的提取历史

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "platform",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "平台过滤",
        "title": "Platform"
      },
      "description": "平台过滤"
    },
    {
      "name": "status",
      "in": "query",
      "required": false,
      "schema": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "状态过滤",
        "title": "Status"
      },
      "description": "状态过滤"
    },
    {
      "name": "page",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "default": 1,
        "title": "Page"
      }
    },
    {
      "name": "page_size",
      "in": "query",
      "required": false,
      "schema": {
        "type": "integer",
        "maximum": 100,
        "minimum": 1,
        "default": 20,
        "title": "Page Size"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExtractionListResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/extraction/upload

登记本地上传文件（仅登记元数据，不做二次下载/转码）
登记用户上传的媒体文件为一条素材提取记录。

仅保存用户提交的文件到存储并登记元数据（文件本身由客户端提交），
**不做**平台下载、BGM 分离、ASR 或二次转码。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "requestBody": {
    "content": {
      "multipart/form-data": {
        "schema": {
          "$ref": "#/components/schemas/Body_upload_file_extraction_api_v1_extraction_upload_post"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExtractionResultResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/extraction/{extraction_id}

获取提取结果
获取提取结果详情

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "extraction_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "integer",
        "title": "Extraction Id"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ExtractionResultResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/extraction/{extraction_id}/download/{resource_type}

跳转到资源直链
按资源类型 302 跳转到解析得到的直链（服务端不二次拉取/转存）。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "extraction_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "integer",
        "title": "Extraction Id"
      }
    },
    {
      "name": "resource_type",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "title": "Resource Type"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## GET /api/v1/extraction/{extraction_id}/progress

获取提取进度 (SSE)
获取提取进度（Server-Sent Events）

注意: 由于 EventSource 不支持自定义 headers，
token 通过 query 参数传递。

资源隔离：鉴权用短会话；SSE 轮询每轮独立开/关 session，
禁止在长连接期间持有 Depends(get_db) 连接。

```json
{
  "parameters": [
    {
      "name": "extraction_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "integer",
        "title": "Extraction Id"
      }
    },
    {
      "name": "token",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "description": "JWT token for SSE authentication",
        "title": "Token"
      },
      "description": "JWT token for SSE authentication"
    }
  ],
  "responses": {
    "200": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {}
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


## POST /api/v1/extraction/{extraction_id}/save-to-assets

保存到资源库（已下线）
云素材库已下线；请使用各端「我的空间」本地记录。

```json
{
  "security": [
    {
      "HTTPBearer": []
    }
  ],
  "parameters": [
    {
      "name": "extraction_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "integer",
        "title": "Extraction Id"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/SaveToAssetsRequest"
        }
      }
    }
  },
  "responses": {
    "410": {
      "description": "Successful Response",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SaveToAssetsResponse"
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  }
}
```


# Components

```json
{
  "schemas": {
    "Body_upload_file_extraction_api_v1_extraction_upload_post": {
      "properties": {
        "file": {
          "type": "string",
          "format": "binary",
          "title": "File",
          "description": "上传的视频或音频文件"
        }
      },
      "type": "object",
      "required": [
        "file"
      ],
      "title": "Body_upload_file_extraction_api_v1_extraction_upload_post"
    },
    "ExtractionAnalyzeRequest": {
      "properties": {
        "url": {
          "type": "string",
          "title": "Url",
          "description": "视频/分享 URL"
        },
        "skip_bgm_separation": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "title": "Skip Bgm Separation",
          "description": "[已废弃/忽略] /extraction 不做 BGM 分离与任何下载上传。需要人声/伴奏分离请调用独立能力 extract_bgm 或 vocal_separate。",
          "deprecated": true
        }
      },
      "type": "object",
      "required": [
        "url"
      ],
      "title": "ExtractionAnalyzeRequest",
      "description": "分析提取请求：纯解析平台元数据与媒体直链，不下载、不上传对象存储。"
    },
    "ExtractionListResponse": {
      "properties": {
        "results": {
          "items": {
            "$ref": "#/components/schemas/ExtractionResultResponse"
          },
          "type": "array",
          "title": "Results",
          "description": "结果列表"
        },
        "total": {
          "type": "integer",
          "title": "Total",
          "description": "总数"
        },
        "page": {
          "type": "integer",
          "title": "Page",
          "description": "当前页",
          "default": 1
        },
        "page_size": {
          "type": "integer",
          "title": "Page Size",
          "description": "每页数量",
          "default": 20
        }
      },
      "type": "object",
      "required": [
        "results",
        "total"
      ],
      "title": "ExtractionListResponse",
      "description": "提取列表响应"
    },
    "ExtractionResource": {
      "properties": {
        "type": {
          "type": "string",
          "title": "Type",
          "description": "类型: video, audio, bgm, cover, subtitle"
        },
        "format": {
          "type": "string",
          "title": "Format",
          "description": "格式: mp4, mp3, jpg, srt等"
        },
        "quality": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Quality",
          "description": "质量: 1080p, 720p等"
        },
        "size": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Size",
          "description": "文件大小(字节)"
        },
        "url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Url",
          "description": "下载URL"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态: pending, ready, failed",
          "default": "pending"
        }
      },
      "type": "object",
      "required": [
        "type",
        "format"
      ],
      "title": "ExtractionResource",
      "description": "提取资源"
    },
    "ExtractionResultResponse": {
      "properties": {
        "source_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Source Url",
          "description": "来源URL"
        },
        "source_type": {
          "type": "string",
          "title": "Source Type",
          "description": "来源类型: url, file"
        },
        "platform": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Platform",
          "description": "平台"
        },
        "id": {
          "type": "integer",
          "title": "Id",
          "description": "提取ID"
        },
        "user_id": {
          "type": "integer",
          "title": "User Id",
          "description": "用户ID"
        },
        "title": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Title",
          "description": "标题"
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Description",
          "description": "描述"
        },
        "author": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Author",
          "description": "作者"
        },
        "author_avatar": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Author Avatar",
          "description": "作者头像"
        },
        "author_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Author Id",
          "description": "作者ID"
        },
        "views": {
          "type": "integer",
          "title": "Views",
          "description": "播放量",
          "default": 0
        },
        "likes": {
          "type": "integer",
          "title": "Likes",
          "description": "点赞数",
          "default": 0
        },
        "duration": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Duration",
          "description": "时长(秒)"
        },
        "duration_formatted": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Duration Formatted",
          "description": "格式化时长"
        },
        "thumbnail_url": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Thumbnail Url",
          "description": "封面图"
        },
        "resources": {
          "items": {
            "$ref": "#/components/schemas/ExtractionResource"
          },
          "type": "array",
          "title": "Resources",
          "description": "资源列表"
        },
        "extracted_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Extracted Text",
          "description": "提取的文本"
        },
        "status": {
          "type": "string",
          "title": "Status",
          "description": "状态",
          "default": "pending"
        },
        "progress": {
          "type": "integer",
          "title": "Progress",
          "description": "进度",
          "default": 0
        },
        "current_step": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Current Step",
          "description": "当前步骤"
        },
        "error_message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Error Message",
          "description": "错误信息"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "title": "Created At",
          "description": "创建时间"
        },
        "completed_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Completed At",
          "description": "完成时间"
        }
      },
      "type": "object",
      "required": [
        "source_type",
        "id",
        "user_id",
        "created_at"
      ],
      "title": "ExtractionResultResponse",
      "description": "提取结果响应"
    },
    "HTTPValidationError": {
      "properties": {
        "detail": {
          "items": {
            "$ref": "#/components/schemas/ValidationError"
          },
          "type": "array",
          "title": "Detail"
        }
      },
      "type": "object",
      "title": "HTTPValidationError"
    },
    "SaveToAssetsRequest": {
      "properties": {
        "resource_types": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Resource Types",
          "description": "要保存的资源类型"
        },
        "folder_id": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Folder Id",
          "description": "目标文件夹ID"
        }
      },
      "type": "object",
      "required": [
        "resource_types"
      ],
      "title": "SaveToAssetsRequest",
      "description": "保存到资源库请求"
    },
    "SaveToAssetsResponse": {
      "properties": {
        "success": {
          "type": "boolean",
          "title": "Success",
          "description": "是否成功"
        },
        "saved_count": {
          "type": "integer",
          "title": "Saved Count",
          "description": "保存数量",
          "default": 0
        },
        "asset_ids": {
          "items": {
            "type": "integer"
          },
          "type": "array",
          "title": "Asset Ids",
          "description": "资源ID列表"
        }
      },
      "type": "object",
      "required": [
        "success"
      ],
      "title": "SaveToAssetsResponse",
      "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"
    }
  },
  "securitySchemes": {
    "HTTPBearer": {
      "type": "http",
      "scheme": "bearer"
    }
  }
}
```