Introduction

API Documentation for Imageurl.dev

Introduction

Welcome to the Imageurl.dev API documentation. This API provides a streamlined, secure, and scalable solution for uploading, saving, and processing media files from various sources. It simplifies file management for web applications, providing multiple upload methods including URL-based uploads, Base64 encoding, local image uploads, and document file uploads.

Supported File Types

  • Images: jpeg, jpg, png, gif, bmp, webp, tiff
  • Documents: pdf, doc, docx, txt, rtf, odt
  • Spreadsheets: xls, xlsx, csv, ods
  • Presentations: ppt, pptx, odp
  • Archives: zip, rar, 7z
  • Other: json, xml

Why Use Imageurl.dev API?

  • Web-Optimized: Reduce image sizes by up to 90% while preserving quality, ensuring faster web performance.
  • Secure: API key-based authentication ensures that only authorized users can upload and manage files.
  • Efficient: Automatically manages storage containers and optimizes uploads for fast processing.
  • Scalable: Built to handle large-scale applications and high volumes of file uploads.
  • Developer-Friendly: Simplifies complex storage operations and offers quick integration into applications.
  • Versatile: Support for multiple file types and upload methods to fit your application needs.

How to Use the API

Prerequisites

Before using the API, ensure you have the following:

  • A valid API key, which can be generated from your dashboard.
  • Content ready to upload (URL, Base64 string, local file, etc.)

Upload Endpoints

The API provides four main endpoints for uploading different types of content:

  1. /api/upload - Upload images via URL
  2. /api/base64 - Upload images via Base64 strings
  3. /api/imageupload - Upload images from local device files
  4. /api/fileupload - Upload documents and other files from local device files

Image Upload Endpoints

URL-based Image Upload

POST https://imageurl.dev/api/upload

Upload images by providing their URLs.

Request Parameters
  • urls (Array of strings) - Required: A list of image URLs to be uploaded.
  • folderName (string) - Required: The name of the folder or container where the images will be stored.
  • imageFormat (string) - Required: The desired format for the exported images (e.g., png, jpeg).
Headers
  • Authorization: Bearer [token] - Required: A valid API token must be included in the request headers.
Example Usage
import axios from "axios";
 
async function uploadImage() {
  try {
    const data = {
      urls: ["https://example.com/image.jpg"],
      folderName: "MyApp",
      imageFormat: "jpeg",
    };
 
    const response = await axios.post("https://imageurl.dev/api/upload", data, {
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer YOUR_TOKEN_HERE",
      },
    });
 
    const responseData = response.data;
    console.log("Uploaded Image URLs:", responseData.uploadedUrls);
    return responseData.uploadedUrls;
  } catch (error) {
    console.error("Error uploading image:", error);
  }
}

Base64 Image Upload

POST https://imageurl.dev/api/base64

Upload images by providing their Base64-encoded strings.

Request Parameters
  • base64Strings (Array of strings) - Required: A list of Base64-encoded strings representing images.
  • folderName (string) - Required: The name of the folder or container where the images will be stored.
  • imageFormat (string) - Required: The desired format for the exported images (e.g., png, jpeg).
Headers
  • Authorization: Bearer [token] - Required: A valid API token must be included in the request headers.
Example Usage
import axios from "axios";
 
async function uploadImagesByBase64() {
  try {
    const data = {
      base64Strings: ["iVBORw0KGgoAAAANSUhEUgAA..."], // Truncated Base64 string
      folderName: "MyApp",
      imageFormat: "jpeg",
    };
 
    const response = await axios.post("https://imageurl.dev/api/base64", data, {
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer YOUR_TOKEN_HERE",
      },
    });
 
    const responseData = response.data;
    return responseData.uploadedUrls;
  } catch (error) {
    console.error("Error uploading Base64 image:", error);
  }
}

Local File Upload Endpoints

Local Image Upload

POST https://imageurl.dev/api/imageupload

Upload images directly from a local device.

Request Parameters
  • files (File) - Required: The image file to be uploaded (multipart/form-data).
  • folderName (string) - Required: The name of the folder or container where the image will be stored.
  • imageFormat (string) - Optional: The desired format for the exported images (e.g., png, jpeg). Defaults to jpeg.
Headers
  • Authorization: Bearer [token] - Required: A valid API token must be included in the request headers.
  • Content-Type: multipart/form-data - Required for file uploads.
Example Usage
import axios from "axios";
 
async function uploadLocalImage(imageFile) {
  try {
    const formData = new FormData();
    formData.append("files", imageFile);
    formData.append("folderName", "MyApp");
    formData.append("imageFormat", "jpeg");
 
    const response = await axios.post(
      "https://imageurl.dev/api/imageupload",
      formData,
      {
        headers: {
          "Content-Type": "multipart/form-data",
          Authorization: "Bearer YOUR_TOKEN_HERE",
        },
      },
    );
 
    const responseData = response.data;
    console.log("Uploaded Image URL:", responseData.uploadedUrls[0]);
    return responseData.uploadedUrls;
  } catch (error) {
    console.error("Error uploading local image:", error);
  }
}
 
// Usage with a file input
document.getElementById("fileInput").addEventListener("change", async (e) => {
  const file = e.target.files[0];
  if (file) {
    const uploadedUrls = await uploadLocalImage(file);
    // Do something with the uploaded URLs
  }
});

Document and File Upload

POST https://imageurl.dev/api/fileupload

Upload documents and other file types directly from a local device.

Request Parameters
  • files (File) - Required: The file to be uploaded (multipart/form-data).
  • folderName (string) - Optional: The name of the folder or container where the file will be stored. Defaults to FileStorage.
Supported File Types
  • Documents: PDF, DOC, DOCX, TXT, RTF, ODT
  • Spreadsheets: XLS, XLSX, CSV, ODS
  • Presentations: PPT, PPTX, ODP
  • Archives: ZIP, RAR, 7Z
  • Other: JSON, XML
Headers
  • Authorization: Bearer [token] - Required: A valid API token must be included in the request headers.
  • Content-Type: multipart/form-data - Required for file uploads.
Example Usage
import axios from "axios";
 
async function uploadDocument(documentFile) {
  try {
    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_TOKEN_HERE",
        },
      },
    );
 
    const responseData = response.data;
    console.log("Uploaded File URL:", responseData.uploadedUrls[0]);
    console.log("File Name:", responseData.fileName);
    console.log("File Type:", responseData.fileType);
    console.log("File Size:", responseData.fileSize);
 
    return responseData.uploadedUrls;
  } catch (error) {
    console.error("Error uploading document:", error);
  }
}
 
// Usage with a file input
document
  .getElementById("documentInput")
  .addEventListener("change", async (e) => {
    const file = e.target.files[0];
    if (file) {
      const uploadedUrls = await uploadDocument(file);
      // Do something with the uploaded URLs
    }
  });

React Component Examples

Image Upload Component Example

Here's an example of a React component that handles image uploads:

import React, { useState, useRef } from "react";
import axios from "axios";
 
const ImageUploader = ({ apiKey }) => {
  const [selectedImage, setSelectedImage] = useState(null);
  const [preview, setPreview] = useState(null);
  const [uploadedUrl, setUploadedUrl] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const fileInputRef = useRef(null);
 
  const handleImageChange = (e) => {
    const file = e.target.files[0];
    if (!file) return;
 
    // Validate image type
    const validTypes = [
      "image/jpeg",
      "image/jpg",
      "image/png",
      "image/gif",
      "image/webp",
    ];
    if (!validTypes.includes(file.type)) {
      setError("Please select a valid image file (JPEG, PNG, GIF, WebP)");
      return;
    }
 
    setSelectedImage(file);
    setError(null);
 
    // Create preview
    const reader = new FileReader();
    reader.onloadend = () => {
      setPreview(reader.result);
    };
    reader.readAsDataURL(file);
  };
 
  const handleUpload = async () => {
    if (!selectedImage) return;
 
    setLoading(true);
    setError(null);
 
    const formData = new FormData();
    formData.append("files", selectedImage);
    formData.append("folderName", "MyAppImages");
    formData.append("imageFormat", "jpeg");
 
    try {
      const response = await axios.post(
        "https://imageurl.dev/api/imageupload",
        formData,
        {
          headers: {
            "Content-Type": "multipart/form-data",
            Authorization: `Bearer ${apiKey}`,
          },
        },
      );
 
      setUploadedUrl(response.data.uploadedUrls[0]);
      setLoading(false);
    } catch (err) {
      setError("Upload failed. Please try again.");
      console.error("Upload error:", err);
      setLoading(false);
    }
  };
 
  return (
    <div className="image-uploader">
      <div className="upload-area" onClick={() => fileInputRef.current.click()}>
        {preview ? (
          <img src={preview} alt="Preview" className="image-preview" />
        ) : (
          <div className="upload-placeholder">Click to select an image</div>
        )}
        <input
          ref={fileInputRef}
          type="file"
          onChange={handleImageChange}
          accept="image/*"
          style={{ display: "none" }}
        />
      </div>
 
      {error && <div className="error-message">{error}</div>}
 
      <button
        onClick={handleUpload}
        disabled={!selectedImage || loading}
        className="upload-button"
      >
        {loading ? "Uploading..." : "Upload Image"}
      </button>
 
      {uploadedUrl && (
        <div className="result">
          <h3>Uploaded Successfully!</h3>
          <a href={uploadedUrl} target="_blank" rel="noopener noreferrer">
            {uploadedUrl}
          </a>
          <img src={uploadedUrl} alt="Uploaded" className="result-image" />
        </div>
      )}
    </div>
  );
};
 
export default ImageUploader;

Document Upload Component Example

Here's an example of a React component that handles document and file uploads:

import React, { useState, useRef } from "react";
import axios from "axios";
 
const FileUploader = ({ apiKey }) => {
  const [selectedFile, setSelectedFile] = useState(null);
  const [uploadedUrl, setUploadedUrl] = useState(null);
  const [fileDetails, setFileDetails] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);
  const fileInputRef = useRef(null);
 
  const getFileIcon = (fileType) => {
    // Return appropriate icon based on file type
    // This is a simplified example - you might want to use a library for icons
    if (fileType.includes("pdf")) return "📄";
    if (fileType.includes("doc")) return "📝";
    if (
      fileType.includes("sheet") ||
      fileType.includes("csv") ||
      fileType.includes("xls")
    )
      return "📊";
    if (fileType.includes("presentation") || fileType.includes("ppt"))
      return "📑";
    if (
      fileType.includes("zip") ||
      fileType.includes("rar") ||
      fileType.includes("7z")
    )
      return "🗄️";
    return "📁";
  };
 
  const handleFileChange = (e) => {
    const file = e.target.files[0];
    if (!file) return;
 
    // Validate file type
    const validExtensions = [
      "pdf",
      "doc",
      "docx",
      "txt",
      "rtf",
      "odt",
      "xls",
      "xlsx",
      "csv",
      "ods",
      "ppt",
      "pptx",
      "odp",
      "zip",
      "rar",
      "7z",
      "json",
      "xml",
    ];
 
    const extension = file.name.split(".").pop().toLowerCase();
    if (!validExtensions.includes(extension)) {
      setError("Please select a valid file type");
      return;
    }
 
    // Validate file size (max 10MB)
    if (file.size > 10 * 1024 * 1024) {
      setError("File size must be less than 10MB");
      return;
    }
 
    setSelectedFile(file);
    setError(null);
    setFileDetails({
      name: file.name,
      size: (file.size / 1024 / 1024).toFixed(2) + " MB",
      type: file.type,
    });
  };
 
  const handleUpload = async () => {
    if (!selectedFile) return;
 
    setLoading(true);
    setError(null);
 
    const formData = new FormData();
    formData.append("files", selectedFile);
    formData.append("folderName", "MyAppDocuments");
 
    try {
      const response = await axios.post(
        "https://imageurl.dev/api/fileupload",
        formData,
        {
          headers: {
            "Content-Type": "multipart/form-data",
            Authorization: `Bearer ${apiKey}`,
          },
        },
      );
 
      setUploadedUrl(response.data.uploadedUrls[0]);
      setLoading(false);
    } catch (err) {
      setError("Upload failed. Please try again.");
      console.error("Upload error:", err);
      setLoading(false);
    }
  };
 
  return (
    <div className="file-uploader">
      <div className="upload-area" onClick={() => fileInputRef.current.click()}>
        {fileDetails ? (
          <div className="file-preview">
            <span className="file-icon">{getFileIcon(fileDetails.type)}</span>
            <p className="file-name">{fileDetails.name}</p>
            <p className="file-size">{fileDetails.size}</p>
          </div>
        ) : (
          <div className="upload-placeholder">
            <p>Click to select a file</p>
            <p className="supported-files">
              Supported formats: PDF, DOC, XLSX, CSV, etc.
            </p>
          </div>
        )}
        <input
          ref={fileInputRef}
          type="file"
          onChange={handleFileChange}
          style={{ display: "none" }}
        />
      </div>
 
      {error && <div className="error-message">{error}</div>}
 
      <button
        onClick={handleUpload}
        disabled={!selectedFile || loading}
        className="upload-button"
      >
        {loading ? "Uploading..." : "Upload File"}
      </button>
 
      {uploadedUrl && (
        <div className="result">
          <h3>File Uploaded Successfully!</h3>
          <a href={uploadedUrl} target="_blank" rel="noopener noreferrer">
            {uploadedUrl}
          </a>
          <div className="file-info">
            <p>File: {fileDetails?.name}</p>
            <p>Size: {fileDetails?.size}</p>
          </div>
        </div>
      )}
    </div>
  );
};
 
export default FileUploader;

Response Format

Image Upload Response

All image upload endpoints (/api/upload, /api/base64, and /api/imageupload) return a response in the following format:

{
  "success": true,
  "containerName": "myapp",
  "uploadedUrls": [
    "https://mycontainer.blob.core.windows.net/myapp/12345_6789.jpeg"
  ],
  "dateCreated": "2023-09-15T12:34:56.789Z",
  "imageFormat": "jpeg"
}

File Upload Response

The file upload endpoint (/api/fileupload) returns a response in the following format:

{
  "success": true,
  "containerName": "filestorage",
  "uploadedUrls": [
    "https://mycontainer.blob.core.windows.net/filestorage/12345_6789.pdf"
  ],
  "fileName": "document.pdf",
  "fileSize": 1024000,
  "fileType": "pdf",
  "dateCreated": "2023-09-15T12:34:56.789Z"
}

Error Handling

All endpoints return appropriate HTTP status codes and error messages:

  • 400 Bad Request: Invalid parameters or file type
  • 401 Unauthorized: Missing or invalid API key
  • 413 Payload Too Large: File size exceeds limits
  • 500 Internal Server Error: Server-side issues

Example error response:

{
  "error": "Invalid file type. File extension not supported."
}

Last updated on March, 2025

How to Use