Skip to main content

​
Upload Image

Upload images to the platform with automatic optimization and storage. Supports both regular images and banner images.

​
Endpoint

POST /api/uploadImage

​
Authentication

Authentication RequiredThis endpoint requires a valid user session. Include session cookies with your request.

​
Request Body

​
image
string
required
Base64-encoded image data or image URL.
​
filename
string
required
Name of the file to be uploaded (including extension).Example: "profile-avatar.jpg", "banner-image.png"
​
isBanner
boolean
default:false
Whether this image is a banner image.
  • true: Image will be processed as a banner (wider aspect ratio)
  • false: Image will be processed as a regular image (e.g., avatar)

​
Response

​
Success Response

Status Code: 200 OK
​
success
boolean
Always true for successful requests.
​
data
string
The URL of the uploaded image. This URL can be used to access the image.
{
  "success": true,
  "data": "https://coffee-advanced-tern-335.mypinata.cloud/ipfs/QmX7Zd..."
}

​
Error Response

Status Code: 401 Unauthorized, 400 Bad Request, or 500 Internal Server Error 
{
  "error": "Unauthorized",
  "status": 401
}

​
Examples

async function uploadImage(file, isBanner = false) {
  // Convert file to base64
  const reader = new FileReader();
  const base64Promise = new Promise((resolve) => {
    reader.onloadend = () => resolve(reader.result);
    reader.readAsDataURL(file);
  });
  
  const base64Image = await base64Promise;
  
  const response = await fetch('/api/uploadImage', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include', // Include session cookies
    body: JSON.stringify({
      image: base64Image,
      filename: file.name,
      isBanner: isBanner
    })
  });
  
  const result = await response.json();
  return result.data; // Image URL
}

// Usage
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
const imageUrl = await uploadImage(file, false);
console.log('Uploaded image URL:', imageUrl);

​
Image Processing

Uploaded images are automatically processed:
  1. Format Conversion: Images may be converted to optimized formats (WebP/AVIF)
  2. Optimization: File size is reduced while maintaining visual quality
  3. Storage: Images are stored on IPFS via Pinata for permanent, decentralized storage
  4. CDN Distribution: Uploaded images are served through Pinata’s CDN for fast global access

​
File Size Limits

While the API doesn’t enforce a hard file size limit, extremely large images may cause timeout issues. Recommended maximum file size is 10MB.For better performance, resize images client-side before uploading.

​
Security Considerations

  • Authentication Required: Only authenticated users can upload images
  • Session Validation: User session is verified on every request
  • File Type Validation: Server validates image data before processing
  • IPFS Storage: Images are stored on decentralized IPFS network
Uploaded images are publicly accessible via their IPFS URLs. Do not upload sensitive or private images through this endpoint.

​
Common Use Cases

  • Profile Avatars: Upload user profile pictures
  • Banner Images: Upload wide banner/cover images for profiles
  • Content Images: Upload images for user-generated content
  • Gallery Images: Build image galleries with uploaded content

Build docs developers (and LLMs) love

Get started for freeTalk to us