v1

SharpWebP REST API

Convert images to ultra-quality WebP programmatically. Integrate SharpWebP into your workflow with a simple REST API.

Get Your API Key in 30 Seconds

Sign up free — no credit card required. Your API key appears in Dashboard Settings after sign-up.

Create Free Account

Contents

Authentication

All API requests require authentication via an API key. Include your key in the X-API-Key request header.

Header
X-API-Key: swp_live_YOUR_API_KEY_HERE

Alternatively, you can use the Authorization: Bearer header:

Alternative header
Authorization: Bearer swp_live_YOUR_API_KEY_HERE
Create a free account to get your API key. Keys start with swp_live_ and are shown only once when created. Store them securely.

Rate Limits

API usage is governed by your plan's daily limits. When you exceed your quota the API returns 429 Too Many Requests.

PlanDaily ImagesDaily UploadMax File Size
Pro 500 5120 MB 200 MB
Business 5,000 51200 MB 200 MB

POST /api/v1/convert

Convert a single image to WebP, AVIF, or JPEG XL. Upload the file as multipart/form-data.

Parameters

NameTypeRequiredDescription
image file Required Image file (JPEG, PNG, GIF, or WebP). Max 50 MB.
format string Optional Output format: webp (default), avif, or jxl. AVIF and JXL require Starter plan or above.
quality string Optional Quality mode: maximum, ultra, high (default), edge_preserving.
resize_width int Optional Target width in pixels. Defaults to the original image width.
resize_height int Optional Target height in pixels. Defaults to the original image height.

cURL Example

curl -X POST https://sharpwebp.com/api/v1/convert \
  -H "X-API-Key: swp_live_YOUR_API_KEY_HERE" \
  -F "image=@photo.jpg" \
  -F "format=webp" \
  -F "quality=high" \
  -F "resize_width=1920" \
  -F "resize_height=1080"

Success Response 200

{
  "success": true,
  "processing_id": "proc_67ab12cd_a1b2c3d4e5f6",
  "download_url": "/download.php?id=proc_67ab12cd_a1b2c3d4e5f6",
  "format": "webp",
  "original_size": 2457600,
  "output_size": 814320,
  "compression_ratio": 0.3314,
  "processing_time": 4.82,
  "dimensions": { "width": 1920, "height": 1080 },
  "quality_score": 0.9871
}

POST /api/v1/batch

Convert multiple images in a single request. Requires the batch_processing feature (Business plan and above). Maximum 20 images per request.

Parameters

NameTypeRequiredDescription
images[] file[] Required Array of image files. Up to 20 per request.
format string Optional Output format: webp (default), avif, or jxl. Applied to all images. AVIF/JXL require Starter+.
quality string Optional Quality mode applied to all images. Default: high.
resize_width int Optional Target width applied to all images.
resize_height int Optional Target height applied to all images.

cURL Example

curl -X POST https://sharpwebp.com/api/v1/batch \
  -H "X-API-Key: swp_live_YOUR_API_KEY_HERE" \
  -F "images[]=@photo1.jpg" \
  -F "images[]=@photo2.png" \
  -F "images[]=@photo3.webp" \
  -F "quality=ultra"

Success Response 200

{
  "success": true,
  "batch_id": "batch_67ab12cd_a1b2c3d4",
  "total": 3,
  "completed": 3,
  "failed": 0,
  "processing_time": 12.41,
  "results": [
    {
      "index": 0,
      "filename": "photo1.jpg",
      "success": true,
      "processing_id": "proc_...",
      "download_url": "/download.php?id=proc_...",
      "original_size": 2457600,
      "output_size": 814320,
      "compression_ratio": 0.3314,
      "processing_time": 3.92
    }
  ]
}

GET /api/v1/status

Check the status of a previous conversion or batch job. Useful for polling after long-running batch requests.

Query Parameters

NameTypeRequiredDescription
processing_id string One required ID from a single conversion.
batch_id string One required ID from a batch conversion.

cURL Example

curl -G https://sharpwebp.com/api/v1/status \
  -H "X-API-Key: swp_live_YOUR_API_KEY_HERE" \
  -d "processing_id=proc_67ab12cd_a1b2c3d4e5f6"

GET /api/v1/account

Retrieve your account details, plan information, current usage, and remaining quota.

cURL Example

curl https://sharpwebp.com/api/v1/account \
  -H "X-API-Key: swp_live_YOUR_API_KEY_HERE"

Success Response 200

{
  "success": true,
  "account": {
    "name": "Jane Developer",
    "email": "jane@example.com",
    "member_since": "2026-01-15 10:30:00"
  },
  "plan": {
    "name": "Pro",
    "slug": "pro",
    "daily_image_limit": 500,
    "daily_upload_mb": 500,
    "max_file_mb": 50,
    "quality_modes": ["high","ultra","maximum","edge_preserving"],
    "features": { "api_access": true, "batch_processing": false }
  },
  "usage": {
    "today": { "images_processed": 42, "bytes_uploaded": 104857600 },
    "remaining": { "images": 458, "upload_bytes": 419430400 },
    "lifetime": { "total_images": 12840, "total_uploaded": 3221225472 }
  },
  "api_keys": { "active_count": 2, "max_allowed": 5 }
}

Error Codes

All error responses follow a consistent JSON envelope. 

{
  "success": false,
  "error": "Human-readable error message.",
  "error_code": "SNAKE_CASE_CODE"
}
The error_code field is included when available and is suitable for programmatic error handling. Common codes: INVALID_FORMAT, PLAN_UPGRADE_REQUIRED, RATE_LIMITED, PROCESSING_ERROR, IO_ERROR.
HTTP CodeMeaningCommon Causes
400 Bad Request Missing or invalid parameters, unsupported file type, corrupt image.
401 Unauthorized Missing, invalid, or expired API key.
403 Forbidden Plan does not include the required feature (e.g. API access, batch processing).
405 Method Not Allowed Wrong HTTP method (e.g. GET instead of POST).
429 Too Many Requests Daily image or upload byte limit exceeded.
500 Internal Server Error Processing failure, server misconfiguration.

Full Examples

Python (requests)

import requests

API_KEY = "swp_live_YOUR_API_KEY_HERE"
BASE    = "https://sharpwebp.com"

# Single conversion
with open("photo.jpg", "rb") as f:
    resp = requests.post(
        f"{BASE}/api/v1/convert",
        headers={"X-API-Key": API_KEY},
        files={"image": ("photo.jpg", f, "image/jpeg")},
        data={"quality": "ultra", "resize_width": "1920"}
    )

data = resp.json()
if data["success"]:
    # Download the result
    dl = requests.get(f"{BASE}{data['download_url']}")
    with open("output.webp", "wb") as out:
        out.write(dl.content)
    print(f"Saved! Compression ratio: {data['compression_ratio']}")
else:
    print(f"Error: {data['error']}")

Node.js (fetch)

const fs = require("fs");
const FormData = require("form-data");

const API_KEY = "swp_live_YOUR_API_KEY_HERE";
const BASE    = "https://sharpwebp.com";

async function convert(imagePath) {
  const form = new FormData();
  form.append("image", fs.createReadStream(imagePath));
  form.append("quality", "high");

  const res = await fetch(`${BASE}/api/v1/convert`, {
    method: "POST",
    headers: { "X-API-Key": API_KEY, ...form.getHeaders() },
    body: form,
  });

  const data = await res.json();
  console.log(data);
  return data;
}

convert("./photo.jpg");

PHP (cURL)

$apiKey = "swp_live_YOUR_API_KEY_HERE";
$url    = "https://sharpwebp.com/api/v1/convert";

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["X-API-Key: {$apiKey}"],
    CURLOPT_POSTFIELDS     => [
        "image"        => new CURLFile("photo.jpg", "image/jpeg"),
        "quality"      => "high",
        "resize_width" => 1920,
    ],
]);

$response = curl_exec($ch);
$data     = json_decode($response, true);
curl_close($ch);

if ($data["success"]) {
    echo "Download: {$data['download_url']}\n";
    echo "Compression: {$data['compression_ratio']}\n";
} else {
    echo "Error: {$data['error']}\n";
}