Logo Foto in URL

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.

Immagini prodotto

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"
}