Come scaricare immagini tramite API?

Chiarimento importante: l’API non consente il "download" nel senso tradizionale. Invece, fornisce URL permanenti a contenuti ottimizzati per il web che la tua applicazione serve agli utenti finali. Questo è disciplinato dalla nostra API License Agreement.

NON scarichi file

L’API Cathopic funziona in modo fondamentalmente diverso dai download tradizionali:

• Nessun trasferimento di file: non ricevi né memorizzi mai i file effettivi di immagine/video

• Accesso tramite URL: l’API fornisce URL che puntano a contenuti ospitati da Cathopic

• Solo ottimizzati per il web: i contenuti vengono serviti con una risoluzione adatta alla visualizzazione digitale

• Nessun file originale: gli originali ad alta risoluzione non sono mai accessibili tramite API

• Sempre ospitati: i contenuti restano sui server di Cathopic o su una CDN autorizzata

Risoluzioni disponibili

L’API fornisce tre dimensioni ottimizzate per il web:

• Small: adatte per miniature e piccoli embed (tipicamente ~400px di larghezza)

• Medium: adatte per contenuti web standard (tipicamente ~800px di larghezza)

• Large: qualità migliore per la visualizzazione web (tipicamente ~1200px di larghezza)

Restrizioni critiche:

• I file originali ad alta risoluzione NON vengono MAI forniti

• Le risoluzioni sono ottimizzate per la visualizzazione su schermo, non per la stampa

• Le dimensioni dei file sono compresse per una consegna web veloce

• Non puoi richiedere risoluzioni personalizzate o qualità originale

Per i termini completi, leggi l’API License Agreement e consulta la documentazione tecnica su api.cathopic.com/docs.

Il download delle immagini prevede due passaggi: licenziare la risorsa con /confirm, quindi usare gli URL restituiti.

Step 1: licenzia la risorsa

Chiama /confirm per licenziare una risorsa per un utente finale specifico:

POST https://api.cathopic.com/confirm
x-api-key: YOUR_API_KEY
{
  "media_id": 1234,
  "usage_type": "website",
  "client_identifier": "user_123"
}

Parametri:

• media_id - L’ID della risorsa dai risultati della tua ricerca

• usage_type - Sia "website" sia "email"

• client_identifier - ID univoco per il tuo utente finale

Step 2: usa gli URL di download

La risposta contiene URL permanenti in più formati:

{
  "download_url": {
    "avif": {
      "320": "https://...",
      "640": "https://...",
      "1280": "https://...",
      "1920": "https://...",
      "2560": "https://..."
    },
    "jpeg": {
      "320": "https://...",
      "640": "https://...",
      "1280": "https://...",
      "1920": "https://...",
      "2560": "https://..."
    }
  }
}

Importante: memorizza gli URL

Gli URL restituiti sono permanenti: salvali nel tuo database:

// Dopo aver chiamato /confirm
const response = await api.confirm(mediaId, userId);
// Salva nel tuo database
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// La prossima volta, recupera dal DB invece di chiamare /confirm di nuovo

Scegliere il formato giusto

Formato AVIF:

• Dimensioni dei file più piccole (migliori prestazioni)

• Migliore compressione

• Consigliato per i browser moderni

• Non supportato nei browser più vecchi

Formato JPEG:

• Compatibilità universale

• Dimensioni dei file più grandi

• Usalo come fallback per i browser più vecchi

Promemoria critico

⚠️ Controlla sempre il tuo database prima di chiamare /confirm. Chiamarlo più volte per lo stesso utente e la stessa risorsa creerà addebiti duplicati.

Documentazione completa su api.cathopic.com/docs.