How to Use

How to Use Imageurl.dev

This guide will walk you through using the Imageurl.dev API for various file upload needs.

Getting Started

1. Obtain Your API Key

Before using any of our endpoints, you'll need an API key:

  1. Sign up or log in to your Imageurl.dev dashboard
  2. Navigate to the API Keys section
  3. Generate a new API key
  4. Copy your key and store it securely

2. Choose the Right Endpoint

Imageurl.dev offers multiple endpoints based on your specific use case:

EndpointPurposeUse When
/api/uploadURL-based image uploadYou have images available at public URLs
/api/base64Base64 image uploadYou have images encoded as Base64 strings
/api/imageuploadLocal image uploadYou need to upload images from user devices
/api/fileuploadDocument uploadYou need to upload documents/files (PDFs, DOCs, etc.)

Image Upload Guide

URL-Based Image Upload

This is the simplest method when you already have images hosted online.

import axios from "axios";
 
// Example: Upload an image from an external URL
async function uploadImage() {
  const data = {
    urls: ["https://example.com/image.jpg"],
    folderName: "MyProject",
    imageFormat: "jpeg",
  };
 
  const response = await axios.post("https://imageurl.dev/api/upload", data, {
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_API_KEY",
    },
  });
 
  return response.data.uploadedUrls;
}

Base64 Image Upload

Useful when you have images already processed on the client side.

// Example: Upload an image from Base64 string
async function uploadBase64Image(base64String) {
  const data = {
    base64Strings: [base64String],
    folderName: "MyProject",
    imageFormat: "png",
  };
 
  const response = await axios.post("https://imageurl.dev/api/base64", data, {
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer YOUR_API_KEY",
    },
  });
 
  return response.data.uploadedUrls;
}

Local Image Upload

Perfect for when you need to upload images directly from a user's device.

// Example: Upload image from file input
async function uploadLocalImage(imageFile) {
  const formData = new FormData();
  formData.append("files", imageFile);
  formData.append("folderName", "UserUploads");
  formData.append("imageFormat", "jpeg");
 
  const response = await axios.post(
    "https://imageurl.dev/api/imageupload",
    formData,
    {
      headers: {
        "Content-Type": "multipart/form-data",
        Authorization: "Bearer YOUR_API_KEY",
      },
    },
  );
 
  return response.data.uploadedUrls;
}
 
// Using with a file input
document.getElementById("imageInput").addEventListener("change", (e) => {
  const file = e.target.files[0];
  if (file) {
    uploadLocalImage(file).then((urls) => {
      console.log("Uploaded image URL:", urls[0]);
    });
  }
});

Document Upload Guide

Upload Documents and Files

Use this method to upload PDFs, spreadsheets, presentations and other file types.

// Example: Upload document from file input
async function uploadDocument(documentFile) {
  const formData = new FormData();
  formData.append("files", documentFile);
  formData.append("folderName", "Documents");
 
  const response = await axios.post(
    "https://imageurl.dev/api/fileupload",
    formData,
    {
      headers: {
        "Content-Type": "multipart/form-data",
        Authorization: "Bearer YOUR_API_KEY",
      },
    },
  );
 
  return {
    url: response.data.uploadedUrls[0],
    fileName: response.data.fileName,
    fileSize: response.data.fileSize,
    fileType: response.data.fileType,
  };
}
 
// Using with a file input
document.getElementById("documentInput").addEventListener("change", (e) => {
  const file = e.target.files[0];
  if (file) {
    uploadDocument(file).then((result) => {
      console.log("Uploaded document:", result);
    });
  }
});

Integration Examples

React Component Integration

Here's how to integrate with a React application:

import { useState } from "react";
import axios from "axios";
 
function UploadComponent() {
  const [file, setFile] = useState(null);
  const [uploadedUrl, setUploadedUrl] = useState(null);
  const [isLoading, setIsLoading] = useState(false);
 
  const handleFileChange = (e) => {
    setFile(e.target.files[0]);
  };
 
  const handleUpload = async () => {
    if (!file) return;
 
    setIsLoading(true);
 
    // Determine if file is an image or document
    const isImage = file.type.startsWith("image/");
    const endpoint = isImage ? "/api/imageupload" : "/api/fileupload";
 
    const formData = new FormData();
    formData.append("files", file);
    formData.append("folderName", isImage ? "Images" : "Documents");
 
    // Add imageFormat if it's an image
    if (isImage) {
      formData.append("imageFormat", "jpeg");
    }
 
    try {
      const response = await axios.post(
        `https://imageurl.dev${endpoint}`,
        formData,
        {
          headers: {
            "Content-Type": "multipart/form-data",
            Authorization: "Bearer YOUR_API_KEY",
          },
        },
      );
 
      setUploadedUrl(response.data.uploadedUrls[0]);
    } catch (error) {
      console.error("Upload failed:", error);
    } finally {
      setIsLoading(false);
    }
  };
 
  return (
    <div>
      <input type="file" onChange={handleFileChange} />
      <button onClick={handleUpload} disabled={!file || isLoading}>
        {isLoading ? "Uploading..." : "Upload"}
      </button>
 
      {uploadedUrl && (
        <div>
          <p>File uploaded successfully!</p>
          <a href={uploadedUrl} target="_blank" rel="noopener noreferrer">
            {uploadedUrl}
          </a>
        </div>
      )}
    </div>
  );
}

Next.js API Route Example

Create your own proxy endpoint in a Next.js application:

// pages/api/proxy-upload.js
import axios from "axios";
import formidable from "formidable";
import fs from "fs";
 
export const config = {
  api: {
    bodyParser: false,
  },
};
 
export default async function handler(req, res) {
  if (req.method !== "POST") {
    return res.status(405).end();
  }
 
  // Parse the incoming form data
  const form = new formidable.IncomingForm();
  form.parse(req, async (err, fields, files) => {
    if (err) {
      return res.status(500).json({ error: "File parsing failed" });
    }
 
    try {
      // Determine file type
      const file = files.file;
      const isImage = file.mimetype.startsWith("image/");
      const endpoint = isImage ? "/api/imageupload" : "/api/fileupload";
 
      // Prepare form data
      const formData = new FormData();
      formData.append("files", fs.createReadStream(file.filepath));
      formData.append("folderName", fields.folderName || "NextJsUploads");
 
      if (isImage) {
        formData.append("imageFormat", fields.imageFormat || "jpeg");
      }
 
      // Forward to Imageurl.dev API
      const response = await axios.post(
        `https://imageurl.dev${endpoint}`,
        formData,
        {
          headers: {
            "Content-Type": "multipart/form-data",
            Authorization: `Bearer ${process.env.IMAGEURL_API_KEY}`,
          },
        },
      );
 
      res.status(200).json(response.data);
    } catch (error) {
      console.error("Upload proxy error:", error);
      res.status(500).json({ error: "Upload failed" });
    }
  });
}

Common Use Cases

Image Gallery

Create an image gallery where users can upload images that are automatically optimized.

Document Management System

Build a document repository where users can upload and manage various file types.

User Avatar Uploads

Implement user profile picture uploads with automatic image optimization.

Form Attachments

Add file attachment capabilities to forms, supporting both images and documents.

Tips and Best Practices

  1. Validate files client-side before uploading to save bandwidth and time
  2. Handle errors gracefully with user-friendly messages
  3. Show progress indicators for large file uploads
  4. Store returned URLs in your application database to reference uploaded files
  5. Set appropriate folder names to keep your storage organized

Rate Limits and Quotas

  • Free tier: 100 uploads per day, max 5MB per file
  • Pro tier: 1,000 uploads per day, max 10MB per file
  • Enterprise tier: Custom limits based on your needs

Exceeding these limits will result in 429 Too Many Requests responses.

Need Help?

If you encounter any issues or have questions about implementing our API:

Introduction