diff --git a/kplayer/core/openapi.json b/kplayer/core/openapi.json
new file mode 100644
index 0000000..7777fd5
--- /dev/null
+++ b/kplayer/core/openapi.json
@@ -0,0 +1,473 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Face Swap API",
+    "description": "Face swapping with GFPGAN v1.4 restoration using filesystem paths",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/": {
+      "get": {
+        "summary": "Root",
+        "description": "API information and documentation",
+        "operationId": "root__get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "title": "Response Root  Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/health": {
+      "get": {
+        "summary": "Health Check",
+        "description": "Health check endpoint with cache statistics",
+        "operationId": "health_check_health_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HealthResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/process-image": {
+      "post": {
+        "summary": "Process Image",
+        "description": "Process a single image with face swapping and GFPGAN restoration\n\n- **input_image_path**: Path to the image to process\n- **source_face_path**: Path to the source face image\n- **output_path**: Optional path for output (default: output.jpg)",
+        "operationId": "process_image_process_image_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProcessImageRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProcessResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/process-folder": {
+      "post": {
+        "summary": "Process Folder",
+        "description": "Process all images in a folder with face swapping and GFPGAN restoration\n\n- **input_folder_path**: Path to folder containing images\n- **source_face_path**: Path to the source face image\n- **output_folder_path**: Optional path to output folder (default: <input_folder>/swap)",
+        "operationId": "process_folder_process_folder_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProcessFolderRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/FolderProcessResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/process-video": {
+      "post": {
+        "summary": "Process Video",
+        "description": "Process a video file with face swapping and GFPGAN restoration\n\n- **input_video_path**: Path to the video to process\n- **source_face_path**: Path to the source face image\n- **output_path**: Optional path for output video (default: output.mp4)",
+        "operationId": "process_video_process_video_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ProcessVideoRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProcessResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/cache/clear": {
+      "post": {
+        "summary": "Clear Cache",
+        "description": "Clear the model cache\n\nThis endpoint clears all cached models from memory.\nUseful for freeing GPU memory or forcing model reload.",
+        "operationId": "clear_cache_cache_clear_post",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "title": "Response Clear Cache Cache Clear Post"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/cache/stats": {
+      "get": {
+        "summary": "Get Cache Stats",
+        "description": "Get detailed cache statistics\n\nReturns information about cached models and cache performance.",
+        "operationId": "get_cache_stats_cache_stats_get",
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "title": "Response Get Cache Stats Cache Stats Get"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "FolderProcessResponse": {
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "title": "Success"
+          },
+          "message": {
+            "type": "string",
+            "title": "Message"
+          },
+          "output_folder": {
+            "type": "string",
+            "title": "Output Folder"
+          },
+          "total_images": {
+            "type": "integer",
+            "title": "Total Images"
+          },
+          "success_count": {
+            "type": "integer",
+            "title": "Success Count"
+          },
+          "failed_count": {
+            "type": "integer",
+            "title": "Failed Count"
+          },
+          "processing_time": {
+            "type": "number",
+            "title": "Processing Time"
+          }
+        },
+        "type": "object",
+        "required": [
+          "success",
+          "message",
+          "output_folder",
+          "total_images",
+          "success_count",
+          "failed_count",
+          "processing_time"
+        ],
+        "title": "FolderProcessResponse"
+      },
+      "HTTPValidationError": {
+        "properties": {
+          "detail": {
+            "items": {
+              "$ref": "#/components/schemas/ValidationError"
+            },
+            "type": "array",
+            "title": "Detail"
+          }
+        },
+        "type": "object",
+        "title": "HTTPValidationError"
+      },
+      "HealthResponse": {
+        "properties": {
+          "status": {
+            "type": "string",
+            "title": "Status"
+          },
+          "version": {
+            "type": "string",
+            "title": "Version"
+          },
+          "cache_stats": {
+            "type": "object",
+            "title": "Cache Stats"
+          }
+        },
+        "type": "object",
+        "required": [
+          "status",
+          "version",
+          "cache_stats"
+        ],
+        "title": "HealthResponse"
+      },
+      "ProcessFolderRequest": {
+        "properties": {
+          "input_folder_path": {
+            "type": "string",
+            "title": "Input Folder Path",
+            "description": "Path to folder containing images"
+          },
+          "source_face_path": {
+            "type": "string",
+            "title": "Source Face Path",
+            "description": "Path to source face image"
+          },
+          "output_folder_path": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Output Folder Path",
+            "description": "Path to output folder (default: <input_folder>/swap)"
+          }
+        },
+        "type": "object",
+        "required": [
+          "input_folder_path",
+          "source_face_path"
+        ],
+        "title": "ProcessFolderRequest",
+        "example": {
+          "input_folder_path": "./images",
+          "output_folder_path": "./output",
+          "source_face_path": "./faces/source.png"
+        }
+      },
+      "ProcessImageRequest": {
+        "properties": {
+          "input_image_path": {
+            "type": "string",
+            "title": "Input Image Path",
+            "description": "Path to input image file"
+          },
+          "source_face_path": {
+            "type": "string",
+            "title": "Source Face Path",
+            "description": "Path to source face image"
+          },
+          "output_path": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Output Path",
+            "description": "Path to output image (default: output.jpg)"
+          }
+        },
+        "type": "object",
+        "required": [
+          "input_image_path",
+          "source_face_path"
+        ],
+        "title": "ProcessImageRequest",
+        "example": {
+          "input_image_path": "./images/target.jpg",
+          "output_path": "./output/result.jpg",
+          "source_face_path": "./faces/source.png"
+        }
+      },
+      "ProcessResponse": {
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "title": "Success"
+          },
+          "message": {
+            "type": "string",
+            "title": "Message"
+          },
+          "output_path": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Output Path"
+          },
+          "processing_time": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Processing Time"
+          }
+        },
+        "type": "object",
+        "required": [
+          "success",
+          "message"
+        ],
+        "title": "ProcessResponse"
+      },
+      "ProcessVideoRequest": {
+        "properties": {
+          "input_video_path": {
+            "type": "string",
+            "title": "Input Video Path",
+            "description": "Path to input video file"
+          },
+          "source_face_path": {
+            "type": "string",
+            "title": "Source Face Path",
+            "description": "Path to source face image"
+          },
+          "output_path": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Output Path",
+            "description": "Path to output video (default: output.mp4)"
+          }
+        },
+        "type": "object",
+        "required": [
+          "input_video_path",
+          "source_face_path"
+        ],
+        "title": "ProcessVideoRequest",
+        "example": {
+          "input_video_path": "./videos/target.mp4",
+          "output_path": "./output/result.mp4",
+          "source_face_path": "./faces/source.png"
+        }
+      },
+      "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"
+      }
+    }
+  }
+}
\ No newline at end of file