Getting Started with the KoalaPic API — Your First Conversion

You can go from zero to a converted image in under 30 seconds. Here’s how to make your first API call.

Step 1: Get Your API Key

Sign in at koalapic.com/api-key/ and click “Generate Key.” Your key starts with kp_ and looks like kp_a1b2c3d4e5.... Copy it immediately — it’s only shown once.

Step 2: Convert an Image

The simplest conversion — upload a file, get back a result:

curl

curl -X POST https://koalapic.com/api/v1/convert \
  -H "Authorization: Bearer kp_your_api_key" \
  -F "file=@photo.png" \
  -F "output_format=webp"

Python

import requests

with open("photo.png", "rb") as f:
    response = requests.post(
        "https://koalapic.com/api/v1/convert",
        headers={"Authorization": "Bearer kp_your_api_key"},
        files={"file": f},
        data={"output_format": "webp"},
    )

data = response.json()
print(f"Status: {data['status']}")
print(f"Download: {data['download_url']}")

JavaScript (Node.js)

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

const form = new FormData();
form.append('file', fs.createReadStream('photo.png'));
form.append('output_format', 'webp');

const response = await fetch('https://koalapic.com/api/v1/convert', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer kp_your_api_key',
  },
  body: form,
});

const data = await response.json();
console.log(data.download_url);

Step 3: Download the Result

The response includes a download_url. Fetch it with another request:

curl -L -o converted.webp "$DOWNLOAD_URL"

Download links expire after 1 hour. Convert and download in your application’s workflow — don’t store URLs for later.

Available Parameters

Error Handling

The API returns standard HTTP status codes:

• 200: Success
• 400: Bad request (invalid format, missing file, etc.)
• 401: Invalid or missing API key
• 429: Rate limit exceeded — wait and retry
• 500: Server error — retry with backoff

Always check the response status before using the result.

Authentication

Every request must include your API key in the Authorization header as a Bearer token. Keys start with kp_ and are tied to your account. You can create multiple keys for different applications and revoke them individually from the dashboard.

Keep your key secret — never commit it to version control or expose it in client-side code. Use environment variables in production:

import os
API_KEY = os.environ["KOALAPIC_API_KEY"]

Rate Limits

Free tier: 30 requests/minute, 1000/day. Check the rate limits guide for details.

Next Steps

• Explore all endpoints in the API documentation
• Try the interactive playground to test requests in your browser
• Set up webhooks for async notifications