upload_file
Upload local files to Gemini Files API for use with AI image generation. Returns file URI and metadata, enabling handling of large files (over 20MB) or repeated use across multiple prompts.
Instructions
Upload a local file through the Gemini Files API and return its URI & metadata. Useful when the image is larger than 20MB or reused across prompts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Server-accessible file path to upload to Gemini Files API. | |
| display_name | No | Optional display name for the uploaded file. |
Implementation Reference
- The core upload_file tool handler function, decorated with @server.tool including tool metadata annotations, defining input schema via Annotated[Field] for 'path' and 'display_name', and implementing logic: logs request, gets file_service, uploads file, returns ToolResult with metadata or handles errors with structured content.@server.tool( annotations={ "title": "Upload file to Gemini Files API", "readOnlyHint": False, "openWorldHint": True, } ) def upload_file( path: Annotated[ str, Field( description="Server-accessible file path to upload to Gemini Files API.", min_length=1, max_length=512, ), ], display_name: Annotated[ Optional[str], Field(description="Optional display name for the uploaded file.", max_length=256), ] = None, ctx: Context = None, ) -> ToolResult: """ Upload a local file through the Gemini Files API and return its URI & metadata. Useful when the image is larger than 20MB or reused across prompts. """ logger = logging.getLogger(__name__) try: logger.info(f"Upload file request: path='{path}', display_name='{display_name}'") # Get service (would be injected in real implementation) file_service = _get_file_service() # Upload file metadata = file_service.upload_file(path, display_name) # Create response summary = f"Successfully uploaded file: {metadata['name']}" # Return as structured content (not image blocks) logger.info(f"Successfully uploaded file: {metadata['name']}") return ToolResult( content=[summary], structured_content={"success": True, "file": metadata} ) except ValidationError as e: logger.error(f"Validation error in upload_file: {e}") return ToolResult( content=[f"Validation error: {e}"], structured_content={"error": "validation_error", "message": str(e)}, ) except FileOperationError as e: logger.error(f"File operation error in upload_file: {e}") return ToolResult( content=[f"File upload failed: {e}"], structured_content={"error": "file_operation_error", "message": str(e)}, ) except Exception as e: logger.error(f"Unexpected error in upload_file: {e}") raise
- nanobanana_mcp_server/core/server.py:37-42 (registration)Imports register_upload_file_tool from tools.upload_file and calls it within _register_tools() to register the upload_file tool on the FastMCP server instance.from ..tools.upload_file import register_upload_file_tool from ..tools.output_stats import register_output_stats_tool from ..tools.maintenance import register_maintenance_tool register_generate_image_tool(self.server) register_upload_file_tool(self.server)
- Private helper _get_file_service() that imports and returns the global file_service instance for use in the handler.def _get_file_service(): """Get the file service instance.""" from ..services import get_file_service return get_file_service()
- Supporting FileService.upload_file method: validates file_path, checks size limit (100MB), uploads via self.gemini_client.upload_file, extracts and returns metadata dict with uri, name, etc.def upload_file(self, file_path: str, display_name: Optional[str] = None) -> Dict[str, Any]: """ Upload a file to Gemini Files API. Args: file_path: Path to the file to upload display_name: Optional display name for the file Returns: Dictionary with file metadata """ try: # Validate file path validate_file_path(file_path) self.logger.info(f"Uploading file: {file_path}") # Check file size file_size = os.path.getsize(file_path) max_size = 100 * 1024 * 1024 # 100MB limit for Files API if file_size > max_size: raise ValidationError( f"File size ({file_size} bytes) exceeds maximum ({max_size} bytes)" ) # Upload file file_obj = self.gemini_client.upload_file(file_path, display_name) # Extract metadata metadata = { "uri": file_obj.uri, "name": file_obj.name, "mime_type": getattr(file_obj, "mime_type", None), "size_bytes": getattr(file_obj, "size_bytes", file_size), "display_name": display_name or os.path.basename(file_path), "original_path": file_path, } self.logger.info(f"Successfully uploaded file: {file_obj.name}") return metadata except ValidationError: raise # Re-raise validation errors except Exception as e: self.logger.error(f"Failed to upload file {file_path}: {e}") raise FileOperationError(f"File upload failed: {e}")