COS Direct Upload Tool and File Operation Examples

One-Sentence Introduction

A complete file upload solution built on Tencent Cloud COS, supporting two integration modes: backend API direct upload and frontend STS temporary credential-based direct upload — including a Next.js frontend example.

Project Purpose

This project delivers an out-of-the-box upload solution for applications integrating with Tencent Cloud Object Storage (COS). It wraps COS operations in a FastAPI backend and provides an STS temporary credential generation endpoint, enabling frontend clients to upload files directly to COS—bypassing the backend entirely and reducing server bandwidth pressure.

Key Features

1. Backend API Upload

Upload files to COS via FastAPI backend endpoints—ideal for small files and server-side use cases.

Features:

• POST /upload: One-click file upload
• Automatic folder organization by year/month
• Returns publicly accessible COS URLs
• Supports multiple API keys mapped to distinct buckets

2. Frontend STS Direct Upload

Browser-based uploads using short-lived STS credentials—optimized for large files and high-concurrency scenarios.

Advantages:

• Files bypass the backend entirely
• STS credentials are secure and time-limited
• Supports multipart (chunked) upload
• Permissions scoped to designated directories
• Includes a ready-to-run Next.js example using cos-js-sdk-v5

3. Multi-Bucket & Multi-Key Management

Supports configuration of multiple COS buckets and corresponding API keys—enabling flexible adoption across diverse projects.

Mapping rules:

• API_KEY → COS_BUCKET + COS_REGION
• API_KEY_2 → COS_BUCKET_2 + COS_REGION_2
• Scalable to unlimited buckets
• Region fallback to global default is supported

4. CORS Configuration & Web Interface

Includes preconfigured CORS settings and a functional web upload interface—ready to run immediately.

Interface features:

• HTML-based upload page
• Drag-and-drop support
• Real-time upload progress visualization
• One-click copy of uploaded file URLs

Use Cases

Frontend Project File Upload

Provides plug-and-play COS direct upload for Next.js, React, and other frontend frameworks.

Shared Upload Service Across Multiple Projects

A single backend service manages multiple COS buckets; different projects integrate using unique API keys.

Large-File Upload Scenarios

Leverages STS direct upload and multipart upload capabilities to handle videos, archives, and other large assets efficiently.

Rapid Prototyping

Serves as production-ready file upload infrastructure for new projects—eliminating boilerplate setup and configuration.

Product Value

• Dual upload modes address varied business requirements
• STS direct upload significantly reduces backend bandwidth usage
• Multi-bucket management enables seamless scaling across projects
• Comprehensive frontend examples accelerate onboarding and reduce integration effort
• Production-ready PM2 deployment configuration included