Documentazione API
L'API richiede un abbonamento Pro o Premium attivo. Autenticati con una chiave API e carica immagini nella stessa libreria del Dashboard. Le quote corrispondono al piano a pagamento sul sito.
Carica un'immagine
POST /api/v1/upload con multipart/form-data.
Parametri
Authorization- Obbligatorio. Header della richiesta. Formato: Bearer LA_TUA_CHIAVE_API.
file- Obbligatorio. Un file binario o dati in base64.
name- Opzionale. Nome file; rilevato automaticamente con upload multipart locale.
Esempio di richiesta
File binario
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=@./product.jpg"
Base64
curl https://phototourl.com/api/v1/upload \ -X POST \ -H "Authorization: Bearer ptu_live_YOUR_KEY" \ -F "file=R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" \ -F "name=pixel.gif"
Per caricare un file locale usa sempre POST. GET non è supportato per l’upload.
Campi di risposta
id- Id risorsa nella libreria.
url- URL CDN da usare sulle pagine prodotto.
fileName- Nome file originale.
fileSize- Dimensione del file in byte.
mimeType- Tipo MIME del file caricato.
createdAt- Ora di upload in UTC, formato YYYY-MM-DD HH:mm:ss.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileName": "product.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}Elenca immagini
GET /api/v1/images con page e pageSize opzionali (max 100).
curl "https://phototourl.com/api/v1/images?page=1&pageSize=20" \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
Campi di risposta
resources- Array di immagini: id, fileName, url, fileSize, mimeType, createdAt.
page- Numero di pagina corrente.
pageSize- Elementi per pagina.
total- Totale immagini in libreria.
{
"resources": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"fileName": "product.jpg",
"url": "https://cdn.phototourl.com/pro/2026-11-05-a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"fileSize": 128472,
"mimeType": "image/jpeg",
"createdAt": "2026-11-05 10:20:30"
}
],
"page": 1,
"pageSize": 20,
"total": 1
}Elimina un'immagine
DELETE /api/v1/images/:id. Rimuove il file dallo storage e dalla libreria.
curl -X DELETE https://phototourl.com/api/v1/images/RESOURCE_ID \ -H "Authorization: Bearer ptu_live_YOUR_KEY"
Campi di risposta
success- true quando l'immagine è stata eliminata.
{ "success": true }Limiti
L'API non è disponibile su Free. Pro e Premium usano i limiti di upload, storage e dimensione file del piano. Se superi un limite, l'API restituisce un errore con upgradeUrl.
Errori
Le richieste fallite restituiscono un codice errore. Gli errori di quota possono includere upgradeUrl.
dailyLimitReached— Limite giornaliero di upload raggiunto (HTTP 429).storageLimitReached— Quota di storage superata (HTTP 413).fileTooLarge— File più grande di quanto consente il piano (HTTP 400).401— Chiave API mancante, non valida o revocata.
{
"error": "dailyLimitReached",
"errorParams": { "limit": 1000 },
"plan": "paid",
"limit": 1000,
"upgradeUrl": "https://www.phototourl.com/pricing"
}