Storage
DYPAI Storage provides S3-compatible file storage with a global CDN, automatic image transformations, and fine-grained access control through three distinct bucket types.
Overview
Every DYPAI project includes a fully managed storage system built on top of S3-compatible infrastructure. Files are automatically distributed to edge locations worldwide, so your users always download from the nearest point of presence. The storage API supports uploads of any file type, on-the-fly image optimization, and granular access control through bucket policies and signed URLs.
Key capabilities of DYPAI Storage:
- Upload, download, and manage files of any type and size
- Organize files into buckets with distinct access policies
- Serve assets through a global CDN with automatic edge caching
- Transform and optimize images on the fly via URL parameters
- Generate time-limited signed URLs for private file access
- Control access at the bucket and file level with security policies
Bucket Types
Buckets are the top-level containers for organizing your files. Each bucket has an access type that determines how files inside it can be reached. You can create as many buckets as you need and mix different types within a single project.
| Type | Access Method | Use Case | URL Pattern |
|---|---|---|---|
| Public | Anyone can read, no authentication required | Marketing assets, product images, public downloads | https://cdn.dypai.ai/<project>/public/<path> |
| Private | Requires a valid API key or signed URL | User documents, internal files, sensitive data | https://cdn.dypai.ai/<project>/private/<path>?token=... |
| Protected | Custom row-level security policies | User-specific uploads, role-based file access | https://cdn.dypai.ai/<project>/protected/<path> |
Public buckets are ideal for content that should be accessible without any authentication, such as website images or downloadable resources. Private buckets require every request to include either an API key in the Authorization header or a valid signed URL. Protected buckets let you write custom policies so that, for example, a user can only access files within their own folder.
logo-v2.png) or setting a shorter cache TTL in bucket settings.File Operations
The Storage API provides a complete set of operations for managing files within your buckets. All operations are available through both the REST API and the client SDKs.
| Operation | Method | Description |
|---|---|---|
| Upload | POST | Upload a new file or replace an existing one |
| Download | GET | Retrieve a file by its path |
| Delete | DELETE | Permanently remove a file from storage |
| Move | POST | Move a file to a different path or bucket |
| Copy | POST | Duplicate a file to a new location |
| List | GET | List all files within a bucket or folder |
Here is an example of uploading a file using the REST API with a standardfetch call:
// Upload a file to a public bucket
const file = document.querySelector('input[type="file"]').files[0];
const response = await fetch(
'https://api.dypai.ai/v1/storage/buckets/avatars/files/user-avatar.png',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': file.type,
'X-Upsert': 'true', // Replace if file already exists
},
body: file,
}
);
const data = await response.json();
if (data.error) {
console.error('Upload failed:', data.error.message);
} else {
console.log('File uploaded:', data.path);
console.log('Public URL:', data.public_url);
}X-Upsert header to true to replace an existing file at the same path instead of receiving a conflict error. This is useful for updating profile pictures or other files that change over time.Image Transformations
DYPAI automatically optimizes and transforms images served from storage. You can request specific dimensions, formats, and quality levels by appending query parameters to the CDN URL. Transformations are processed at the edge and cached for subsequent requests.
| Parameter | Type | Description | Example |
|---|---|---|---|
width | number | Target width in pixels | width=400 |
height | number | Target height in pixels | height=300 |
resize | string | Resize mode: cover, contain, fill, or inside | resize=cover |
quality | number | Output quality from 1 to 100 | quality=80 |
format | string | Output format: webp, avif, png, or jpeg | format=webp |
For example, to serve a 400px-wide WebP thumbnail of a product image:
https://cdn.dypai.ai/my-project/public/products/hero.jpg?width=400&format=webp&quality=80&resize=coverThe first request triggers the transformation, and all subsequent requests for the same combination of parameters are served directly from the edge cache with no processing delay.
Signed URLs
Signed URLs provide temporary, time-limited access to files in private buckets. They are useful when you need to give a user access to a specific file without exposing your API key or creating a permanent public link.
// Generate a signed URL valid for 1 hour (3600 seconds)
const response = await fetch(
'https://api.dypai.ai/v1/storage/buckets/documents/files/report.pdf/signed-url',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
expiresIn: 3600,
}),
}
);
const { signedUrl } = await response.json();
// signedUrl looks like:
// https://cdn.dypai.ai/my-project/private/documents/report.pdf?token=eyJ...&expires=1739...
console.log('Temporary download link:', signedUrl);Signed URLs respect the expiration time exactly. Once expired, the URL returns a403 Forbidden response. You can generate as many signed URLs as needed for the same file, each with its own expiration time.
CDN & Caching
Every file served through DYPAI Storage is delivered via a global CDN with edge locations on six continents. This ensures low-latency downloads regardless of where your users are located.
- Public buckets: Files are cached at the edge with a default TTL of 1 year. The CDN automatically serves stale content while revalidating in the background.
- Private/Protected buckets: Files are cached at the edge for the duration of the signed URL or the cache header you set. Expired tokens always result in a cache miss.
- Image transformations: Each unique combination of transformation parameters is cached independently, so the first request may be slower while subsequent requests are instant.
POST /v1/storage/cache/purgeendpoint with the file path. Cache purges propagate to all edge locations within 30 seconds.File Size Limits
The maximum file size for a single upload depends on your project's plan. Uploads that exceed the limit receive a 413 Payload Too Large response.
| Plan | Max File Size | Total Storage |
|---|---|---|
| Free | 50 MB | 1 GB |
| Starter | 250 MB | 25 GB |
| Pro | 5 GB | 500 GB |
For files larger than 100 MB, we recommend using multipart uploads. The API will automatically handle chunking and resumable uploads when you set theX-Upload-Strategy: multipart header.
Next steps
- Configure buckets -- Create and manage buckets with access policies
- File management -- Upload, download, move, and delete files