Comment télécharger des images via l’API ? - Centre d’aide

Clarification importante : L’API ne permet pas de « télécharger » au sens traditionnel. À la place, elle fournit des URL permanentes vers du contenu optimisé pour le web que votre application sert aux utilisateurs finaux. Cela est régi par notre Contrat de licence de l’API.

Vous NE téléchargez PAS de fichiers

L’API Cathopic fonctionne fondamentalement différemment des téléchargements traditionnels :

Aucun transfert de fichier : vous ne recevez ni ne stockez jamais les fichiers image/vidéo réels
Accès par URL : l’API fournit des URL qui pointent vers du contenu hébergé par Cathopic
Optimisé pour le web uniquement : le contenu est servi dans une résolution adaptée à l’affichage numérique
Pas de fichiers originaux : les originaux haute résolution ne sont jamais accessibles via l’API
Toujours hébergé : le contenu reste sur les serveurs de Cathopic ou sur un CDN autorisé

Résolutions disponibles

L’API fournit trois tailles optimisées pour le web :

Petite : adaptée aux vignettes et aux petites intégrations (typiquement ~400 px de large)
Moyenne : adaptée au contenu web standard (typiquement ~800 px de large)
Grande : meilleure qualité pour l’affichage web (typiquement ~1200 px de large)

Restrictions critiques :

Les fichiers originaux haute résolution ne sont JAMAIS fournis
Les résolutions sont optimisées pour l’écran, pas pour l’impression
Les tailles de fichiers sont compressées pour une livraison web rapide
Vous ne pouvez pas demander des résolutions personnalisées ni la qualité originale

Pour connaître l’ensemble des conditions, lisez le Contrat de licence de l’API et consultez la documentation technique à api.cathopic.com/docs.

Le « téléchargement » d’images implique deux étapes : licencier la ressource avec /confirm, puis utiliser les URL renvoyées.

Étape 1 : licencier la ressource

Appelez /confirm pour licencier une ressource pour un utilisateur final spécifique :

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

Paramètres :

media_id - L’identifiant de la ressource provenant de vos résultats de recherche
usage_type - Soit « website » soit « email »
client_identifier - Identifiant unique pour votre utilisateur final

Étape 2 : utiliser les URL de téléchargement

La réponse contient des URL permanentes dans plusieurs formats :

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

Important : stocker les URL

Les URL renvoyées sont permanentes : stockez-les dans votre base de données :

// Après avoir appelé /confirm
const response = await api.confirm(mediaId, userId);
// Stocker dans votre base de données
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// La prochaine fois, récupérez depuis la base de données au lieu d’appeler /confirm à nouveau

Choisir le bon format

Format AVIF :

Taille de fichier plus petite (meilleures performances)
Meilleure compression
Recommandé pour les navigateurs modernes
Non pris en charge dans les navigateurs plus anciens

Format JPEG :

Compatibilité universelle
Taille de fichier plus grande
À utiliser comme solution de repli pour les navigateurs plus anciens

Rappel critique

⚠️ Vérifiez toujours votre base de données avant d’appeler /confirm. L’appeler plusieurs fois pour le même utilisateur et la même ressource créera des frais en double.

Documentation complète à api.cathopic.com/docs.