Documentation

Introduction

OgenSync Files is a powerful image processing and delivery service that helps you transform, optimize, and deliver images at scale. Think of it as a simpler alternative to Cloudinary.

Key Features

Quick Start

Get started in 3 simple steps:

POST https://files.ogensync.com/api/upload
Authorization: Bearer YOUR_API_TOKEN
Content-Type: multipart/form-data

file: [your-image-file]

{
  "success": true,
  "id": "abc123xyz",
  "url": "https://files.ogensync.com/img/abc123xyz"
}

https://files.ogensync.com/img/abc123xyz?w=400&h=300&f=webp&q=80

Authentication

All API requests require authentication using an API token. You can generate tokens from your Dashboard → API Tokens.

Header Authentication

Authorization: Bearer YOUR_API_TOKEN

Uploading Images

Dashboard Upload

The easiest way to upload is through the Dashboard. Simply drag and drop your images or browse to select files.

API Upload

For programmatic uploads, use the upload endpoint:

curl -X POST https://files.ogensync.com/api/upload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@/path/to/image.jpg"

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://files.ogensync.com/api/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' },
  body: formData
});

const data = await response.json();
console.log('Image URL:', data.url);

import requests

url = 'https://files.ogensync.com/api/upload'
headers = {'Authorization': 'Bearer YOUR_API_TOKEN'}
files = {'file': open('image.jpg', 'rb')}

response = requests.post(url, headers=headers, files=files)
print('Image URL:', response.json()['url'])

Supported Formats

JPEG, PNG, WebP, GIF, AVIF, TIFF, SVG

Size Limits

• Maximum file size: 50MB
• Maximum dimensions: 10,000 x 10,000 pixels

Transformations

Transform images on-the-fly by adding query parameters to your image URL.

Resize Examples

Format Conversion

Quality & Effects

Geometry & Rotation

Delivery URL

Your images are served from our global CDN. You can use two URL formats:

Query Parameter Format

https://files.ogensync.com/img/{IMAGE_ID}?{PARAMETERS}

Path-Based Format Recommended

https://files.ogensync.com/img/{IMAGE_ID}/{TRANSFORMATIONS}

Example URLs (Path-Based)

# Original image
https://files.ogensync.com/img/abc123xyz

# Resize to 300x300, quality 80, cover fit
https://files.ogensync.com/img/abc123xyz/w_300-h_300-q_80-fit_cover

# Convert to WebP, resize width 500
https://files.ogensync.com/img/abc123xyz/w_500-f_webp-q_85

# Grayscale effect with blur
https://files.ogensync.com/img/abc123xyz/gray_true-blur_5

# Multiple transformations combined
https://files.ogensync.com/img/abc123xyz/w_800-h_600-q_90-fit_contain-f_avif

# Smart Crop (Face Detection Simulation)
https://files.ogensync.com/img/abc123xyz/w_500-h_500-fit_cover-crop_100,50,300,300

# Creative Effects (Grayscale + Blur + Border via Background)
https://files.ogensync.com/img/abc123xyz/w_600-h_400-fit_contain-bg_black-gray_true-blur_2

# Orientation Fix (Rotate + Flip)
https://files.ogensync.com/img/abc123xyz/rotate_90-flip_true

Example URLs (Query Params)

# Original image
https://files.ogensync.com/img/abc123

# Resized to 400px width, WebP format
https://files.ogensync.com/img/abc123?w=400&f=webp

# Thumbnail with quality optimization
https://files.ogensync.com/img/abc123?w=150&h=150&fit=cover&q=80

Using Images in HTML

Easily integrate optimized images into your websites using standard HTML tags.

Basic Image Tag

<img 
  src="https://files.ogensync.com/img/abc123xyz/w_800-h_600-fit_cover" 
  alt="Description" 
  width="800" 
  height="600"
  loading="lazy"
>

Responsive Images (srcset)

<img 
  src="https://files.ogensync.com/img/abc123xyz/w_800"
  srcset="https://files.ogensync.com/img/abc123xyz/w_400 400w,
          https://files.ogensync.com/img/abc123xyz/w_800 800w,
          https://files.ogensync.com/img/abc123xyz/w_1200 1200w"
  sizes="(max-width: 600px) 100vw, 800px"
  alt="Responsive Image"
>

Modern Formats with <picture>

<picture>
  <source srcset="https://files.ogensync.com/img/abc123xyz/f_avif" type="image/avif">
  <source srcset="https://files.ogensync.com/img/abc123xyz/f_webp" type="image/webp">
  <img src="https://files.ogensync.com/img/abc123xyz/f_jpeg" alt="Modern Format Image">
</picture>

CSS Background

.hero-section {
  background-image: url('https://files.ogensync.com/img/abc123xyz/w_1920-q_80-blur_5');
  background-size: cover;
  background-position: center;
}

URL Parameters Reference

API Endpoints

{
  "success": true,
  "id": "abc123xyz",
  "url": "https://files.ogensync.com/img/abc123xyz",
  "size": 125430
}

Usage Tracking

The system tracks "processing" (creating new variants) and "url calls" (viewing images).

Rate Limits

Integration Examples

React Component

function OgenSyncImage({ imageId, width, height }) {
  // Using path-based syntax for better caching
  const src = `https://files.ogensync.com/img/${imageId}/w_${width}-h_${height}-f_webp`;
  return <img src={src} alt="" loading="lazy" />;
}

// Usage
<OgenSyncImage imageId="abc123xyz" width={400} height={300} />

HTML with Responsive Images

<picture>
  <source srcset="https://files.ogensync.com/img/abc123xyz/w_400-f_webp" type="image/webp">
  <img src="https://files.ogensync.com/img/abc123xyz/w_400" alt="Description">
</picture>