{ "openapi": "3.1.0", "info": { "title": "Extraction", "description": "API service for App Factory reusable modules", "version": "1.0.0", "x-source-commit": "f33cc2b935f31b36240d724948dc8b9c765430cc" }, "paths": { "/api/v1/extraction/analyze": { "post": { "tags": [ "extraction" ], "summary": "分析 URL（纯素材解析，不下载不上传）", "description": "分析 URL 并解析素材元数据与直链。\n\n**仅数据提取**：返回平台 video/audio/cover 直链与标题等元数据。\n**不会**下载媒体文件、**不会**上传到对象存储、**不会**做 BGM/ASR。\n需要落盘/转存、口播文案、人声分离请走独立原子能力。", "operationId": "analyze_url_api_v1_extraction_analyze_post", "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" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/extraction/upload": { "post": { "tags": [ "extraction" ], "summary": "登记本地上传文件（仅登记元数据，不做二次下载/转码）", "description": "登记用户上传的媒体文件为一条素材提取记录。\n\n仅保存用户提交的文件到存储并登记元数据（文件本身由客户端提交），\n**不做**平台下载、BGM 分离、ASR 或二次转码。", "operationId": "upload_file_extraction_api_v1_extraction_upload_post", "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" } } } } }, "security": [ { "HTTPBearer": [] } ] } }, "/api/v1/extraction/{extraction_id}": { "get": { "tags": [ "extraction" ], "summary": "获取提取结果", "description": "获取提取结果详情", "operationId": "get_extraction_api_v1_extraction__extraction_id__get", "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" } } } } } } }, "/api/v1/extraction/{extraction_id}/progress": { "get": { "tags": [ "extraction" ], "summary": "获取提取进度 (SSE)", "description": "获取提取进度（Server-Sent Events）\n\n注意: 由于 EventSource 不支持自定义 headers，\ntoken 通过 query 参数传递。\n\n资源隔离：鉴权用短会话；SSE 轮询每轮独立开/关 session，\n禁止在长连接期间持有 Depends(get_db) 连接。", "operationId": "get_extraction_progress_api_v1_extraction__extraction_id__progress_get", "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" } } } } } } }, "/api/v1/extraction/history": { "get": { "tags": [ "extraction" ], "summary": "获取提取历史", "description": "获取用户的提取历史", "operationId": "get_extraction_history_api_v1_extraction_history_get", "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" } } } } } } }, "/api/v1/extraction/{extraction_id}/save-to-assets": { "post": { "tags": [ "extraction" ], "summary": "保存到资源库（已下线）", "description": "云素材库已下线；请使用各端「我的空间」本地记录。", "operationId": "save_to_assets_api_v1_extraction__extraction_id__save_to_assets_post", "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" } } } } } } }, "/api/v1/extraction/{extraction_id}/download/{resource_type}": { "get": { "tags": [ "extraction" ], "summary": "跳转到资源直链", "description": "按资源类型 302 跳转到解析得到的直链（服务端不二次拉取/转存）。", "operationId": "download_resource_api_v1_extraction__extraction_id__download__resource_type__get", "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" } } } } } } } }, "components": { "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" } } }, "servers": [ { "url": "https://api.sniphunter.com" } ] }