{ "openapi": "3.1.0", "info": { "title": "Item Storage API", "version": "1.2.1", "description": "公开分享解析无需身份；账号上传下载使用 Cloudflare Access。文档不收集凭据。" }, "paths": { "/api/v1/health": { "get": { "summary": "Health", "operationId": "health_api_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "跨站写入或无效签名" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } } } }, "/api/v1/projects": { "get": { "summary": "Projects", "operationId": "projects_api_v1_projects_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "跨站写入或无效签名" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } } } }, "/api/v1/files": { "get": { "summary": "Listing", "operationId": "listing_api_v1_files_get", "parameters": [ { "name": "folder_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,18}$" }, { "type": "null" } ], "title": "Folder Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "跨站写入或无效签名" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } } }, "post": { "summary": "Upload", "operationId": "upload_api_v1_files_post", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_upload_api_v1_files_post" } } } }, "responses": { "201": { "description": "上传与云端回读校验通过", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "202": { "description": "云端已接收但回读未确认：按返回编号重试下载，不要重复上传", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResult" } } } }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "跨站写入或无效签名" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } } } }, "/api/v1/files/{file_id}/link": { "post": { "summary": "Link", "operationId": "link_api_v1_files__file_id__link_post", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "expires_in", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 86400, "minimum": 60, "default": 3600, "title": "Expires In" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "跨站写入或无效签名" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } } } }, "/api/v1/files/{file_id}/download": { "get": { "summary": "Download", "operationId": "download_api_v1_files__file_id__download_get", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "Range", "in": "header", "required": false, "schema": { "type": "string" }, "example": "bytes=0-1023" } ], "responses": { "200": { "description": "原文件附件", "headers": { "X-Content-SHA256": { "schema": { "type": "string" }, "description": "实际交付的原文件 SHA-256" }, "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=..." } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "206": { "description": "验证完整云端副本后返回指定字节片段", "headers": { "X-Content-SHA256": { "schema": { "type": "string" }, "description": "实际交付的原文件 SHA-256" }, "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=..." } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "416": { "description": "Range 不满足文件范围" }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "跨站写入或无效签名" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } } } }, "/d/{file_id}": { "get": { "summary": "Signed Download", "operationId": "signed_download_d__file_id__get", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "expires", "in": "query", "required": true, "schema": { "type": "integer", "title": "Expires" } }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string", "title": "Signature" } }, { "name": "Range", "in": "header", "required": false, "schema": { "type": "string" }, "example": "bytes=0-1023" } ], "responses": { "200": { "description": "原文件附件", "headers": { "X-Content-SHA256": { "schema": { "type": "string" }, "description": "实际交付的原文件 SHA-256" }, "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=..." } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "206": { "description": "验证完整云端副本后返回指定字节片段", "headers": { "X-Content-SHA256": { "schema": { "type": "string" }, "description": "实际交付的原文件 SHA-256" }, "Content-Disposition": { "schema": { "type": "string" }, "description": "attachment; filename=..." } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "416": { "description": "Range 不满足文件范围" }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "跨站写入或无效签名" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } } } }, "/public/api/resolve": { "post": { "tags": [ "免登录分享解析" ], "summary": "Resolve", "operationId": "resolve_public_api_resolve_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareInput" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareResult" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "401": { "description": "Access 身份缺失或无效（边缘也可能返回登录跳转）" }, "403": { "description": "提取码错误或跨站请求" }, "429": { "description": "并发传输繁忙" }, "502": { "description": "上游响应或完整性错误" }, "503": { "description": "上游不可用或需要人工验证" } }, "security": [] } } }, "components": { "schemas": { "Body_upload_api_v1_files_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_upload_api_v1_files_post" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ShareInput": { "properties": { "url": { "type": "string", "maxLength": 2048, "minLength": 1, "title": "Url" }, "password": { "type": "string", "maxLength": 64, "title": "Password", "default": "" } }, "additionalProperties": false, "type": "object", "required": [ "url" ], "title": "ShareInput" }, "ShareResult": { "properties": { "name": { "type": "string", "title": "Name" }, "direct_url": { "type": "string", "title": "Direct Url" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size" }, "resolved_at": { "type": "integer", "title": "Resolved At" }, "requires_login": { "type": "boolean", "title": "Requires Login" }, "message": { "type": "string", "title": "Message" } }, "type": "object", "required": [ "name", "direct_url", "size", "resolved_at", "requires_login", "message" ], "title": "ShareResult" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "UploadResult": { "type": "object", "required": [ "id", "name", "size", "sha256", "verified", "download_url" ], "properties": { "id": { "type": "string", "pattern": "^\\d{1,18}$" }, "name": { "type": "string" }, "size": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "verified": { "type": "boolean" }, "download_url": { "type": "string", "format": "uri" }, "verification_error": { "type": "string" }, "message": { "type": "string" } } } }, "securitySchemes": { "AccessClientId": { "type": "apiKey", "in": "header", "name": "CF-Access-Client-Id" }, "AccessClientSecret": { "type": "apiKey", "in": "header", "name": "CF-Access-Client-Secret" }, "AccessBrowserSession": { "type": "apiKey", "in": "cookie", "name": "CF_Authorization" } } }, "servers": [ { "url": "https://item.bismih520.com" } ], "externalDocs": { "url": "https://bismih-lanzou-docs.pages.dev/" }, "security": [ { "AccessClientId": [], "AccessClientSecret": [] }, { "AccessBrowserSession": [] } ] }