{
  "openapi": "3.1.0",
  "info": {
    "title": "Base64 파일 업로드 API",
    "description": "Base64 인코딩을 통해 파일 서버에 파일 업로드",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://files-api.evolink.ai",
      "description": "파일 서비스 환경"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/files/upload/base64": {
      "post": {
        "summary": "Base64 파일 업로드",
        "description": "- Base64 인코딩 및 Data URL 형식 지원\n- 파일 유형 자동 식별 및 분류 저장\n- 접근 가능한 파일 URL 및 다운로드 링크 반환\n- 파일은 72시간 후 만료됩니다\n- 현재 사용자 할당량이 제한되어 있습니다. 할당량이 소진되면 업로드가 실패합니다. 영구 저장이 필요한 경우 로컬에 저장해 주세요\n\n**참고:**\n파일 업로드 API 기본 URL은 `https://files-api.evolink.ai`입니다",
        "operationId": "uploadFileBase64",
        "tags": [
          "파일 업로드"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Base64UploadRequest"
              },
              "examples": {
                "base64_upload": {
                  "summary": "Base64 파일 업로드",
                  "value": {
                    "base64_data": "data:image/png;base64,iVBORw0KGgo..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "파일이 성공적으로 업로드되었습니다",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Base64UploadRequest": {
        "type": "object",
        "required": [
          "base64_data"
        ],
        "properties": {
          "base64_data": {
            "type": "string",
            "description": "Base64 인코딩된 파일 데이터\n\n**지원 형식:**\n- Data URL 형식: `data:image/png;base64,iVBORw0KGgo...`\n- 순수 Base64 인코딩: `iVBORw0KGgo...`\n\n**참고:**\n- 요청당 최대 `1`개 파일\n- 지원 파일 형식: 이미지(JPEG, PNG, GIF, WebP), 동영상(MP4, MOV, WebM), 오디오(MP3, WAV, M4A, AAC, FLAC, OGG)\n- Data URL 접두사가 있으면 접두사에 선언된 형식을 사용하고, 순수 Base64는 파일 내용으로 형식을 자동 판별합니다",
            "example": "data:image/png;base64,iVBORw0KGgo..."
          },
          "upload_path": {
            "type": "string",
            "description": "사용자 정의 업로드 경로\n\n**참고:**\n- 지정하지 않으면 시스템이 파일 유형에 따라 자동으로 분류합니다",
            "example": "avatars"
          },
          "file_name": {
            "type": "string",
            "description": "사용자 정의 파일 이름\n\n**참고:**\n- 지정하지 않으면 시스템이 자동으로 고유한 파일 이름을 생성합니다",
            "example": "avatar.png"
          }
        }
      },
      "FileUploadResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "요청 성공 여부",
            "example": true
          },
          "code": {
            "type": "integer",
            "description": "응답 상태 코드",
            "example": 200
          },
          "msg": {
            "type": "string",
            "description": "응답 메시지",
            "example": "파일이 성공적으로 업로드되었습니다"
          },
          "data": {
            "$ref": "#/components/schemas/FileData"
          }
        }
      },
      "FileData": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "고유 파일 식별자",
            "example": "file_abc123"
          },
          "file_name": {
            "type": "string",
            "description": "저장된 파일 이름",
            "example": "avatar.png"
          },
          "original_name": {
            "type": "string",
            "description": "원본 파일 이름",
            "example": "avatar.png"
          },
          "file_size": {
            "type": "integer",
            "description": "파일 크기 (바이트)",
            "example": 2048
          },
          "mime_type": {
            "type": "string",
            "description": "파일 MIME 유형",
            "example": "image/png"
          },
          "upload_path": {
            "type": "string",
            "description": "파일 저장 경로",
            "example": "avatars"
          },
          "file_url": {
            "type": "string",
            "format": "uri",
            "description": "파일 접근 URL",
            "example": "https://files.evolink.ai/avatars/avatar.png"
          },
          "download_url": {
            "type": "string",
            "format": "uri",
            "description": "파일 다운로드 URL",
            "example": "https://files.evolink.ai/api/v1/files/download/file_abc123"
          },
          "upload_time": {
            "type": "string",
            "format": "date-time",
            "description": "업로드 시간 (ISO 8601 형식)",
            "example": "2025-10-09T00:00:00+08:00"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "파일 만료 시간 (ISO 8601 형식)",
            "example": "2025-10-12T00:00:00+08:00"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "##모든 API는 Bearer Token 인증이 필요합니다##\n\n**API Key 받기:**\n\n[API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 받으세요\n\n**요청 헤더에 추가:**\n```\nAuthorization: Bearer YOUR_API_KEY\n```"
      }
    }
  },
  "tags": [
    {
      "name": "파일 업로드",
      "description": "파일 업로드 관련 API"
    }
  ]
}