Overview

The Image Splitting API provides a powerful way to programmatically split images into multiple segments. You can split images vertically, horizontally, or in a grid pattern, and receive URLs to access each split segment.

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoints

Split Image

Split an image into multiple segments based on the specified parameters.

POST/api/v1/split-image

Request Parameters

Parameter	Type	Required	Description
imageUrl	string	Yes	URL of the image to split
outputFormat	string	No	Output format (png, jpeg, webp, or "original"). Default: png
splitHeightCount	number	No	Number of rows to split into (equal parts)
splitHeightPixel	number	No	Height in pixels for each segment
splitWidthCount	number	No	Number of columns to split into (equal parts)
splitWidthPixel	number	No	Width in pixels for each segment

Example Request

{
  "imageUrl": "https://example.com/path/to/image.jpg",
  "outputFormat": "png",
  "splitWidthCount": 3,
  "splitHeightCount": 2
}

Example Response

{
  "success": true,
  "height": 800,
  "width": 1200,
  "rows": 2,
  "columns": 3,
  "splitImageUrls": [
    "https://storage.example.com/image-splitter/split-images/uuid_1_1_block.png",
    "https://storage.example.com/image-splitter/split-images/uuid_1_2_block.png",
    "https://storage.example.com/image-splitter/split-images/uuid_1_3_block.png",
    "https://storage.example.com/image-splitter/split-images/uuid_2_1_block.png",
    "https://storage.example.com/image-splitter/split-images/uuid_2_2_block.png",
    "https://storage.example.com/image-splitter/split-images/uuid_2_3_block.png"
  ],
  "zipFileUrl": "https://storage.example.com/image-splitter/zip-files/uuid.zip"
}

Cloud Storage

The API uses cloud storage (Cloudflare R2) to store the split images and ZIP files. This provides:

Better reliability through enterprise-grade cloud storage
Fast download speeds from global CDN
High scalability for many concurrent users
Persistent access to files even after server restarts

The URLs returned by the API point directly to the cloud storage and can be used immediately.

Error Handling

The API returns appropriate HTTP status codes for different error scenarios:

400 Bad Request: Missing required parameters or invalid values
401 Unauthorized: Invalid or missing API key
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server-side processing error

Error responses include an error message explaining the issue:

{
  "error": "Error description",
  "message": "Additional error details"
}

Usage Examples

JavaScript Example

const response = await fetch('https://your-app.vercel.app/api/v1/split-image', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    imageUrl: 'https://example.com/path/to/image.jpg',
    splitHeightCount: 2,
    splitWidthCount: 3,
    outputFormat: 'png'
  })
});

const result = await response.json();
console.log(result);

cURL Example

curl -X POST https://your-app.vercel.app/api/v1/split-image \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "imageUrl": "https://example.com/path/to/image.jpg",
    "outputFormat": "png",
    "splitHeightCount": 2,
    "splitWidthCount": 3
  }'