API-dokumentaatio
Integroi kuvien optimointi suoraan sovellukseesi yhdellä yksinkertaisella REST API -kutsulla.
Todennus
Kaikki API-kutsut vaativat voimassa olevan API-avaimen. Lähetä avain otsikossa X-API-Key tai kyselyparametrina api_key.
Ota yhteyttä saadaksesi API-avaimen.
# Otsikon kautta (suositeltu)
curl -H "X-API-Key: API_AVAIMESI" ...
# Kyselyparametrin kautta
curl "...?api_key=API_AVAIMESI"
curl -H "X-API-Key: API_AVAIMESI" ...
# Kyselyparametrin kautta
curl "...?api_key=API_AVAIMESI"
POST /api/v1/optimize
Optimoi kuva ja valinnaisesti muunna se toiseen formaattiin. Palauttaa optimoidun kuvan suoraan.
Parametrit
| Parametri | Tyyppi | Kuvaus |
|---|---|---|
image Pakollinen |
File | Optimoitava kuvatiedosto. Enint. 2 MB (voidaan nostaa API-avainkohtaisesti) ja enint. 2000×2000 pikseliä (ei koske SVG:tä). Formaatit: JPEG, PNG, WebP, GIF, AVIF, BMP, TIFF, SVG. |
output_format Valinnainen |
String | Muunna kuva tähän formaattiin. Arvot: jpg, png, webp, gif, avif. Jos jätetään pois, alkuperäinen formaatti säilytetään. |
ratio Valinnainen |
String | Enimmäiskoko muodossa LEVEYSxKORKEUS (esim. 1000x1000). Kuva skaalataan mahtumaan laatikkoon, kuvasuhde säilyy, eikä sitä koskaan suurenneta. |
quality Valinnainen |
Integer 1–10 | Kuinka aggressiivinen pakkaus on. 10 (oletus) = maksimipakkaus kaikilla häviöllisillä vaiheilla. 1 = vain häviötön uudelleenpakkaus (~10 % maksimipakkauksesta, ei laadun heikkenemistä). Väliarvot suodattavat pois häviölliset vaiheet laatukynnyksen alapuolelta. |
response Valinnainen |
String | Aseta arvoksi json saadaksesi JSON-vastauksen metatiedoilla ja latauslinkillä kuvan sijaan. |
Vastaus (binaarinen / oletus)
Kuva palautetaan suoraan oikealla Content-Type-otsikolla. Lisämetatiedot ovat otsikoissa:
| Otsikko | Merkitys |
|---|---|
X-Original-Size | Alkuperäisen kuvan koko tavuina |
X-Optimized-Size | Optimoidun tiedoston koko tavuina |
X-Savings-Percent | Säästö prosentteina |
Vastaus (JSON)
Jos response=json lähetetään mukana. HUOM: download_url-osoitteen takana oleva tiedosto poistetaan heti ensimmäisen latauksen jälkeen tai säilytysajan kuluttua (oletus 10 minuuttia).
{
"success": true,
"original_size": 245832,
"optimized_size": 98412,
"savings_percent": 59.9,
"output_format": "webp",
"mime_type": "image/webp",
"download_url": "/download.php?id=abc123...",
"expires_at": "2025-01-15 14:30:00"
}
"success": true,
"original_size": 245832,
"optimized_size": 98412,
"savings_percent": 59.9,
"output_format": "webp",
"mime_type": "image/webp",
"download_url": "/download.php?id=abc123...",
"expires_at": "2025-01-15 14:30:00"
}
Koodiesimerkit
cURL
# Optimoi PNG-kuva (palauttaa kuvan suoraan)
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@min-bild.png" \
--output optimerad.png \
https://img.klema.se/api/v1/optimize
# Muunna JPEG WebP:ksi
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@foto.jpg" \
-F "output_format=webp" \
--output foto.webp \
https://img.klema.se/api/v1/optimize
# Skaalaa enint. 1000x1000 ja konservatiivinen pakkaus (quality=3)
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@foto.jpg" \
-F "ratio=1000x1000" \
-F "quality=3" \
--output foto.jpg \
https://img.klema.se/api/v1/optimize
# Hae JSON-vastaus metatiedoilla
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@min-bild.png" \
-F "response=json" \
https://img.klema.se/api/v1/optimize
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@min-bild.png" \
--output optimerad.png \
https://img.klema.se/api/v1/optimize
# Muunna JPEG WebP:ksi
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@foto.jpg" \
-F "output_format=webp" \
--output foto.webp \
https://img.klema.se/api/v1/optimize
# Skaalaa enint. 1000x1000 ja konservatiivinen pakkaus (quality=3)
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@foto.jpg" \
-F "ratio=1000x1000" \
-F "quality=3" \
--output foto.jpg \
https://img.klema.se/api/v1/optimize
# Hae JSON-vastaus metatiedoilla
curl -X POST \
-H "X-API-Key: API_AVAIMESI" \
-F "image=@min-bild.png" \
-F "response=json" \
https://img.klema.se/api/v1/optimize
Python
import requests
# Optimoi ja lataa
response = requests.post(
"https://img.klema.se/api/v1/optimize",
headers={"X-API-Key": "API_AVAIMESI"},
files={"image": open("bild.png", "rb")},
data={"output_format": "webp"}
)
with open("optimerad.webp", "wb") as f:
f.write(response.content)
print(f"Säästö: {response.headers['X-Savings-Percent']}%")
# Optimoi ja lataa
response = requests.post(
"https://img.klema.se/api/v1/optimize",
headers={"X-API-Key": "API_AVAIMESI"},
files={"image": open("bild.png", "rb")},
data={"output_format": "webp"}
)
with open("optimerad.webp", "wb") as f:
f.write(response.content)
print(f"Säästö: {response.headers['X-Savings-Percent']}%")
JavaScript (Node.js)
const fs = require('fs');
const FormData = require('form-data');
const form = new FormData();
form.append('image', fs.createReadStream('bild.jpg'));
form.append('output_format', 'webp');
form.append('response', 'json');
const res = await fetch('https://img.klema.se/api/v1/optimize', {
method: 'POST',
headers: { 'X-API-Key': 'API_AVAIMESI' },
body: form
});
const data = await res.json();
console.log(`Säästö: ${data.savings_percent}%`);
const FormData = require('form-data');
const form = new FormData();
form.append('image', fs.createReadStream('bild.jpg'));
form.append('output_format', 'webp');
form.append('response', 'json');
const res = await fetch('https://img.klema.se/api/v1/optimize', {
method: 'POST',
headers: { 'X-API-Key': 'API_AVAIMESI' },
body: form
});
const data = await res.json();
console.log(`Säästö: ${data.savings_percent}%`);
PHP
$ch = curl_init('https://img.klema.se/api/v1/optimize');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_AVAIMESI'],
CURLOPT_POSTFIELDS => [
'image' => new CURLFile('bild.png'),
'output_format' => 'webp',
],
]);
$result = curl_exec($ch);
file_put_contents('optimerad.webp', $result);
curl_close($ch);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['X-API-Key: API_AVAIMESI'],
CURLOPT_POSTFIELDS => [
'image' => new CURLFile('bild.png'),
'output_format' => 'webp',
],
]);
$result = curl_exec($ch);
file_put_contents('optimerad.webp', $result);
curl_close($ch);
Virhekoodit
| HTTP-koodi | Merkitys |
|---|---|
400 | Virheellinen pyyntö – kuva puuttuu, virheellinen formaatti tms. |
401 | Virheellinen tai puuttuva API-avain. |
403 | API on poistettu käytöstä. |
405 | Väärä HTTP-metodi (käytä POST). |
500 | Palvelinvirhe optimoinnin aikana. |
// Virhevastaukset palautetaan aina JSON-muodossa
{
"error": "Invalid or missing API key."
}
{
"error": "Invalid or missing API key."
}
Tuetut formaatit
| Formaatti | Syöte | Tuloste |
|---|---|---|
JPEG | Kyllä | Kyllä |
PNG | Kyllä | Kyllä |
WebP | Kyllä | Kyllä |
GIF | Kyllä | Kyllä |
AVIF | Kyllä | Kyllä |
BMP | Kyllä | Ei |
TIFF | Kyllä | Ei |
SVG | Kyllä | Ei |