Back to API Docs

API Quickstart

Convert your first image in under 30 seconds. No signup required.

Get your API key (optional)

You can use the API without a key (10 requests/min, 50/day) or sign up free for higher limits (30/min, 500/day).

To get a key:

Create an account at /account/signup/
Go to Dashboard → API Keys
Click Generate Key — your key starts with kp_

Step 2 works without a key — don't let this block you.

Convert your first image

The easiest way: convert from a URL. We provide a sample image so this works out of the box.

Option A — Convert from URL (easiest)

# Convert a sample image to WebP
curl -X POST https://koalapic.com/api/v1/convert/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://koalapic.com/static/sample.jpg", "output_format": "webp"}'

import requests

resp = requests.post("https://koalapic.com/api/v1/convert/url", json={
    "url": "https://koalapic.com/static/sample.jpg",
    "output_format": "webp",
})
conversion = resp.json()
print(f"Converting... ID: {conversion['id']}")

const resp = await fetch("https://koalapic.com/api/v1/convert/url", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://koalapic.com/static/sample.jpg",
    output_format: "webp",
  }),
});
const conversion = await resp.json();

$response = file_get_contents('https://koalapic.com/api/v1/convert/url', false,
    stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode([
            'url'           => 'https://koalapic.com/static/sample.jpg',
            'output_format' => 'webp',
        ]),
    ]])
);
$conversion = json_decode($response, true);

Option B — Convert a local file

curl -X POST https://koalapic.com/api/v1/convert \
  -F "file=@photo.jpg" \
  -F "output_format=webp"

with open("photo.jpg", "rb") as f:
    resp = requests.post("https://koalapic.com/api/v1/convert",
        files={"file": f},
        data={"output_format": "webp"},
    )
conversion = resp.json()

const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("output_format", "webp");

const resp = await fetch("https://koalapic.com/api/v1/convert", {
  method: "POST",
  body: formData,
});
const conversion = await resp.json();

$ch = curl_init('https://koalapic.com/api/v1/convert');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => [
        'file'          => new CURLFile('photo.jpg'),
        'output_format' => 'webp',
    ],
]);
$conversion = json_decode(curl_exec($ch), true);
curl_close($ch);

Response:

"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"output_format": "webp"

Save the id — you'll need it to check status and download.

Check conversion status

Poll the status endpoint until status is completed.

curl https://koalapic.com/api/v1/convert/CONVERSION_ID/status

import time

while True:
    status = requests.get(
        f"https://koalapic.com/api/v1/convert/{conversion['id']}/status"
    ).json()
    if status["status"] == "completed":
        break
    if status["status"] == "failed":
        print(f"Error: {status.get('error_message')}")
        exit(1)
    time.sleep(1)

let status;
do {
  await new Promise(r => setTimeout(r, 1000));
  const poll = await fetch(
    `https://koalapic.com/api/v1/convert/${conversion.id}/status`
  );
  status = await poll.json();
} while (status.status === "pending" || status.status === "processing");

do {
    sleep(1);
    $status = json_decode(file_get_contents(
        'https://koalapic.com/api/v1/convert/' . $conversion['id'] . '/status'
    ), true);
} while (in_array($status['status'], ['pending', 'processing']));

Response when completed:

{
  "status": "completed",
  "download_url": "/api/v1/download/abc123...",
  "download_token": "abc123...",
  "output_size": 45230,
  "input_size": 102400
}

When status is completed, your file is ready.

Download the result

curl -O https://koalapic.com/api/v1/download/DOWNLOAD_TOKEN

result = requests.get(f"https://koalapic.com{status['download_url']}")
with open("output.webp", "wb") as f:
    f.write(result.content)
print(f"Done! Saved output.webp ({len(result.content):,} bytes)")

if (status.status === "completed") {
  const file = await fetch(`https://koalapic.com${status.download_url}`);
  const blob = await file.blob();
  console.log(`Done! Size: ${blob.size} bytes`);
}

if ($status['status'] === 'completed') {
    $file = file_get_contents('https://koalapic.com' . $status['download_url']);
    file_put_contents('output.webp', $file);
    echo "Done! Saved output.webp (" . strlen($file) . " bytes)\n";
}

That's it! You've converted your first image via the API.

Next steps

Higher rate limits (30/min vs 10/min), usage tracking, and webhook support. Sign up free → Manage keys

Convert up to 50 images at once with POST /api/v1/convert/url/batch. See batch docs

Use SSE (Server-Sent Events) instead of polling for instant progress updates. See SSE docs

Get notified when conversions complete via HMAC-signed webhook callbacks. See webhook docs

Compress images with smart quality (POST /api/v1/compress) or resize by percentage, pixels, or preset. Full API reference

Ready for the full reference?

Read the API Docs Try the Playground

Complete examples

Copy-paste a full working script for Steps 2–4 combined:

import requests
import time

# Step 2: Start conversion
resp = requests.post("https://koalapic.com/api/v1/convert/url", json={
    "url": "https://koalapic.com/static/sample.jpg",
    "output_format": "webp",
})
conversion = resp.json()
print(f"Converting... ID: {conversion['id']}")

# Step 3: Wait for completion
while True:
    status = requests.get(
        f"https://koalapic.com/api/v1/convert/{conversion['id']}/status"
    ).json()
    if status["status"] == "completed":
        break
    if status["status"] == "failed":
        print(f"Error: {status.get('error_message')}")
        exit(1)
    time.sleep(1)

# Step 4: Download
result = requests.get(f"https://koalapic.com{status['download_url']}")
with open("output.webp", "wb") as f:
    f.write(result.content)
print(f"Done! Saved output.webp ({len(result.content):,} bytes)")

// Step 2: Start conversion
const resp = await fetch("https://koalapic.com/api/v1/convert/url", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://koalapic.com/static/sample.jpg",
    output_format: "webp",
  }),
});
const conversion = await resp.json();

// Step 3: Poll until done
let status;
do {
  await new Promise(r => setTimeout(r, 1000));
  const poll = await fetch(
    `https://koalapic.com/api/v1/convert/${conversion.id}/status`
  );
  status = await poll.json();
} while (status.status === "pending" || status.status === "processing");

// Step 4: Download
if (status.status === "completed") {
  const file = await fetch(`https://koalapic.com${status.download_url}`);
  const blob = await file.blob();
  console.log(`Done! Size: ${blob.size} bytes`);
}

#!/bin/bash
# Complete KoalaPic API conversion example

# Step 2: Start conversion
RESPONSE=$(curl -s -X POST https://koalapic.com/api/v1/convert/url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://koalapic.com/static/sample.jpg", "output_format": "webp"}')

ID=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "Converting... ID: $ID"

# Step 3: Poll until done
while true; do
  STATUS=$(curl -s https://koalapic.com/api/v1/convert/$ID/status)
  STATE=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  [ "$STATE" = "completed" ] && break
  [ "$STATE" = "failed" ] && echo "Failed!" && exit 1
  sleep 1
done

# Step 4: Download
TOKEN=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['download_token'])")
curl -O https://koalapic.com/api/v1/download/$TOKEN
echo "Done!"

<?php
// Complete KoalaPic API conversion example

// Step 2: Start conversion
$response = file_get_contents('https://koalapic.com/api/v1/convert/url', false,
    stream_context_create(['http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode([
            'url'           => 'https://koalapic.com/static/sample.jpg',
            'output_format' => 'webp',
        ]),
    ]])
);
$conversion = json_decode($response, true);
echo "Converting... ID: " . $conversion['id'] . "\n";

// Step 3: Poll until done
do {
    sleep(1);
    $status = json_decode(file_get_contents(
        'https://koalapic.com/api/v1/convert/' . $conversion['id'] . '/status'
    ), true);
} while (in_array($status['status'], ['pending', 'processing']));

// Step 4: Download
if ($status['status'] === 'completed') {
    $file = file_get_contents('https://koalapic.com' . $status['download_url']);
    file_put_contents('output.webp', $file);
    echo "Done! Saved output.webp (" . strlen($file) . " bytes)\n";
}