Skip to main content

​
Quickstart Guide

This guide will help you get started with VisionFly’s image optimization and transformation API in just a few minutes.

​
Prerequisites

  • A VisionFly account (Sign up at visionfly.ai)
  • Your API key and API secret (available in your dashboard)
  • An image file to upload

​
Step 1: Get Your API Key

  1. Sign in to your VisionFly dashboard
  2. Navigate to the API Keys section
  3. Create a new API key or use an existing one
  4. Copy your API key and API secret

​
Step 2: Upload Your First Image

First, let’s upload an image to get a CDN URL. This URL will be your base image that you can use for all transformations: 
curl -X POST "https://api.visionfly.ai/upload" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/your/image.jpg"
This will return a JSON response with your CDN URL: 
{
  "success": true,
  "error": "",
  "cdn_url": "https://cdn.visionfly.ai/<user_id>/images/your-image.jpg",
  "size": 12345,
  "content_type": "image/jpeg"
}

​
Understanding VisionFly URLs

VisionFly uses a structured URL format for all images:
  1. Base Image URL (from upload): 
    https://cdn.visionfly.ai/<user_id>/path_to_your_image.format
    • <user_id>: Your unique user identifier
    • path_to_your_image: The path where your image is stored
    • format: Original image format (jpg, png, etc.)
  2. Transformed Image URL: 
    https://cdn.visionfly.ai/<user_id>/path_to_your_image&f=auto&w=100.format
    • Same base structure as the original
    • Transformation parameters are added as query parameters
    • The image is served directly from our CDN
Important: The transform endpoint can only work with URLs that were generated by the upload endpoint. These are considered your “base images”. All transformed versions are derived from these base images.

​
Step 3: Transform Your Image

Now that you have a CDN URL, let’s transform the image. We’ll resize it to 800px width while maintaining aspect ratio: 
curl -X GET "https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800" \
-H "X-API-Key: YOUR_API_KEY"
This will return a JSON response with the transformed image URL: 
{
  "success": true,
  "error": "",
  "public_url": "https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800&f=auto",
  "size": 12345,
  "content_type": "image/webp"
}

​
Step 4: Add More Transformations

Let’s enhance our image with some additional transformations: 
curl -X GET "https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800&q=80&f=auto&sharp=20" \
-H "X-API-Key: YOUR_API_KEY"
This will:
  • Resize to 800px width
  • Set quality to 80%
  • Automatically choose the best format (WebP/AVIF)
  • Apply slight sharpening

​
Step 5: Create Responsive Images

Generate a srcset for responsive images using your CDN URL: 
curl -X GET "https://api.visionfly.ai/generate/srcset?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=400,800,1200&f=auto" \
-H "X-API-Key: YOUR_API_KEY"
This will return a JSON response with the srcset information: 
{
  "srcset": "https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=400&f=auto&q=80 400w, https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800&f=auto&q=80 800w, https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=1200&f=auto&q=80 1200w",
  "sizes": "(max-width: 1200px) 100vw, 1200px",
  "default": "https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800&f=auto&q=80"
}
You can use this response to create a responsive image in your HTML: 
<img
  srcset="
    https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=400&f=auto&q=80   400w,
    https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800&f=auto&q=80   800w,
    https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=1200&f=auto&q=80 1200w
  "
  sizes="(max-width: 1200px) 100vw, 1200px"
  src="https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800&f=auto&q=80"
  alt="Responsive image"
/>
You can also customize the widths and format: 
curl -X GET "https://api.visionfly.ai/generate/srcset?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=429,880,1280&f=png" \
-H "X-API-Key: YOUR_API_KEY"
This will return a response with your custom widths: 
{
  "srcset": "https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=429&f=png&q=80 429w, https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=880&f=png&q=80 880w, https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=1280&f=png&q=80 1280w",
  "sizes": "(max-width: 1280px) 100vw, 1280px",
  "default": "https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=880&f=png&q=80"
}

​
Step 6: Apply Image Effects

Let’s try some image effects on your uploaded image: 
curl -X GET "https://api.visionfly.ai/transform?src=https://cdn.visionfly.ai/<user_id>/images/your-image.jpg&w=800&bri=10&con=5&sat=-10" \
-H "X-API-Key: YOUR_API_KEY"
This will:
  • Increase brightness by 10%
  • Increase contrast by 5%
  • Decrease saturation by 10%

​
Use VisionFly SDK in Your Application

This guide will help you get up and running with VisionFly in less than 5 minutes. Follow these simple steps to start optimizing and transforming your images.
It is highly recommended to use the SDK over raw HTTP requests because the SDK is more secure and is more fast than making raw HTTP requests.

​
Step 1: Sign Up for VisionFly

Make sure you have the VisionFly API key and API secret already.

​
Step 2: Install the VisionFly SDK

Add the VisionFly SDK to your JavaScript project using npm or yarn: 
# Using npm
npm install visionfly-sdk

# Using yarn
yarn add visionfly-sdk

​
Step 3: Initialize the SDK

import { VisionFly } from "visionfly-sdk";

// Initialize the SDK with your API credentials
const visionfly = new VisionFly({
  apiKey: "your-api-key",
  apiSecret: "your-api-secret",
});

​
Step 4: Upload an Image

Upload an image to the VisionFly CDN to get started: 
// Example function to handle file upload
async function uploadImage(file) {
  try {
    // Upload the image to VisionFly
    const result = await visionfly.uploadImage({
      file: file,
      publicId: "your-project-id",
    });

    // The result contains the CDN URL for your uploaded image
    console.log("Image uploaded successfully!");
    console.log("CDN URL:", result.public_url);

    return result.public_url;
  } catch (error) {
    console.error("Upload failed:", error);
  }
}

// Usage example with a file input
document.getElementById("fileInput").addEventListener("change", async (e) => {
  const file = e.target.files[0];
  if (file) {
    const cdnUrl = await uploadImage(file);
    // Use the CDN URL for further transformations
  }
});

​
Step 5: Transform and Optimize Images

Now that you have your image on the CDN, you can transform it by adding parameters to the URL: 
// Transform an image that's already on the VisionFly CDN
async function getOptimizedImage(cdnUrl) {
  const transformedUrl = await visionfly.transformImage({
    src: cdnUrl,
    width: 800,
    height: 600,
    quality: 85,
    format: "webp",
  });

  return transformedUrl;
}

// Example usage
const optimizedUrl = await getOptimizedImage(
  "https://cdn.visionfly.ai/user123/image.jpg"
);
document.getElementById("myImage").src = optimizedUrl;

​
Step 6: Generate Responsive Images

Create responsive image sets for different screen sizes: 
async function createResponsiveImage(cdnUrl) {
  const srcSet = await visionfly.getSrcSet({
    src: cdnUrl,
    widths: [400, 800, 1200, 1600],
    format: "webp",
    quality: 80,
  });

  // The result contains the srcset string and a default URL
  return {
    srcset: srcSet.srcset,
    sizes: srcSet.sizes,
    defaultUrl: srcSet.default,
  };
}

// Example usage
const responsiveData = await createResponsiveImage(
  "https://cdn.visionfly.ai/user123/image.jpg"
);

// Apply to an image element
const img = document.getElementById("responsiveImage");
img.srcset = responsiveData.srcset;
img.sizes = responsiveData.sizes;
img.src = responsiveData.defaultUrl;

​
Complete Example

Here’s a complete example showing the full workflow from upload to display: 
import { VisionFly } from "visionfly-sdk";

// Initialize the SDK
const visionfly = new VisionFly({
  apiKey: "your-api-key",
  apiSecret: "your-api-secret",
});

// Function to handle the entire process
async function processImage(file) {
  try {
    // Step 1: Upload the image
    const uploadResult = await visionfly.uploadImage({
      file: file,
      publicId: "your-project-id",
    });

    const cdnUrl = uploadResult.public_url;
    console.log("Image uploaded to:", cdnUrl);

    // Step 2: Get a transformed version
    const optimizedUrl = await visionfly.transformImage({
      src: cdnUrl,
      width: 800,
      quality: 85,
      format: "webp",
      sharpen: 10,
    });

    console.log("Optimized image URL:", optimizedUrl);

    // Step 3: Generate responsive versions
    const responsiveData = await visionfly.getSrcSet({
      src: cdnUrl,
      widths: [400, 800, 1200],
      format: "webp",
    });

    console.log("Responsive srcset:", responsiveData.srcset);

    // Step 4: Display the image
    document.getElementById("previewImage").src = optimizedUrl;

    // Step 5: Apply responsive image attributes
    const responsiveImg = document.getElementById("responsiveImage");
    responsiveImg.srcset = responsiveData.srcset;
    responsiveImg.sizes = responsiveData.sizes;
    responsiveImg.src = responsiveData.default;

    return {
      cdnUrl,
      optimizedUrl,
      responsiveData,
    };
  } catch (error) {
    console.error("Error processing image:", error);
  }
}

// Event listener for file input
document.getElementById("fileInput").addEventListener("change", async (e) => {
  const file = e.target.files[0];
  if (file) {
    await processImage(file);
  }
});

​
Next Steps

Now that you’ve got the basics covered, explore:
  • Use Cases - See common implementations and best practices
  • API Reference - Explore the complete API documentation
Ready to take your images to the next level? Let’s dive deeper into VisionFly’s capabilities!

​
Next Steps