Hoe kan ik afbeeldingen downloaden via de API?

Belangrijke verduidelijking: De API staat geen "downloaden" toe in de traditionele zin. In plaats daarvan biedt hij permanente URL's naar web-geoptimaliseerde content die je applicatie aan eindgebruikers aanbiedt. Dit wordt geregeld door onze API-licentieovereenkomst.

Je downloadt GEEN bestanden

De Cathopic API werkt fundamenteel anders dan traditionele downloads:

• Geen bestandsdownloads: Je ontvangt of bewaart nooit de daadwerkelijke afbeeldings-/videobestanden

• Toegang via URL: De API levert URL's die verwijzen naar content die door Cathopic wordt gehost

• Alleen web-geoptimaliseerd: Content wordt geleverd in een resolutie die geschikt is voor digitale weergave

• Geen originele bestanden: Originele bestanden met hoge resolutie zijn NOOIT via de API toegankelijk

• Altijd gehost: Content blijft op Cathopic-servers of op een geautoriseerde CDN

Beschikbare resoluties

De API biedt drie web-geoptimaliseerde formaten:

• Klein: Geschikt voor thumbnails en kleine inbeddingen (typisch ~400px breed)

• Middelgroot: Goed voor standaard webcontent (typisch ~800px breed)

• Groot: Beste kwaliteit voor webweergave (typisch ~1200px breed)

Kritieke beperkingen:

• Originele bestanden met hoge resolutie worden NOOIT geleverd

• Resoluties zijn geoptimaliseerd voor schermweergave, niet voor print

• Bestandsgroottes zijn gecomprimeerd voor snelle weblevering

• Je kunt geen aangepaste resoluties of originele kwaliteit aanvragen

Voor de volledige voorwaarden lees je de volledige API-licentieovereenkomst en bekijk je de technische documentatie op api.cathopic.com/docs.

Afbeeldingen downloaden gebeurt in twee stappen: licenseren van de resource met /confirm, en vervolgens de geretourneerde URL's gebruiken.

Stap 1: Licentieer de resource

Roep /confirm aan om een resource te licenseren voor een specifieke eindgebruiker:

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

Parameters:

• media_id - Het resource-ID uit je zoekresultaten

• usage_type - Ofwel "website" of "email"

• client_identifier - Unieke ID voor je eindgebruiker

Stap 2: Gebruik de download-URL's

Het antwoord bevat permanente URL's in meerdere formaten:

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

Belangrijk: Bewaar de URL's

De URL's die worden teruggegeven zijn permanent—bewaar ze in je database:

// Nadat je /confirm hebt aangeroepen
const response = await api.confirm(mediaId, userId);
// Bewaar in je database
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// Haal de volgende keer uit de DB in plaats van opnieuw /confirm aan te roepen

Kies het juiste formaat

AVIF-formaat:

• Kleinere bestandsgroottes (betere prestaties)

• Betere compressie

• Aanbevolen voor moderne browsers

• Niet ondersteund in oudere browsers

JPEG-formaat:

• Universele compatibiliteit

• Grotere bestandsgroottes

• Gebruik als fallback voor oudere browsers

Kritieke herinnering

⚠️ Controleer altijd eerst je database voordat je /confirm aanroept. Door het meerdere keren aan te roepen voor dezelfde gebruiker en resource ontstaan er dubbele kosten.

Volledige documentatie op api.cathopic.com/docs.