Wie lade ich Bilder über die API herunter?

Wichtige Klarstellung: Die API ermöglicht kein „Herunterladen“ im herkömmlichen Sinne. Stattdessen stellt sie dauerhafte URLs zu weboptimierten Inhalten bereit, die Ihre Anwendung den Endnutzern bereitstellt. Dies wird durch unsere API-Lizenzvereinbarung geregelt.

Sie laden keine Dateien herunter

Die Cathopic API funktioniert grundsätzlich anders als herkömmliche Downloads:

• Keine Dateitransfers: Sie erhalten oder speichern niemals die eigentlichen Bild-/Videodateien

• Zugriff über URLs: Die API stellt URLs bereit, die auf von Cathopic gehostete Inhalte zeigen

• Nur weboptimiert: Inhalte werden in einer für die digitale Anzeige geeigneten Auflösung bereitgestellt

• Keine Originaldateien: Hochauflösende Originale sind über die API niemals zugänglich

• Immer gehostet: Inhalte bleiben auf den Cathopic-Servern oder einem autorisierten CDN

Verfügbare Auflösungen

Die API stellt drei weboptimierte Größen bereit:

• Klein: Geeignet für Thumbnails und kleine Einbettungen (typischerweise ~400 px breit)

• Mittel: Gut für Standard-Webinhalte (typischerweise ~800 px breit)

• Groß: Beste Qualität für die Webanzeige (typischerweise ~1200 px breit)

Wichtige Einschränkungen:

• Hochauflösende Originaldateien werden NIEMALS bereitgestellt

• Auflösungen sind für die Bildschirmanzeige optimiert, nicht für den Druck

• Dateigrößen werden für eine schnelle Webbereitstellung komprimiert

• Sie können keine benutzerdefinierten Auflösungen oder Originalqualität anfordern

Für die vollständigen Bedingungen lesen Sie die vollständige API-Lizenzvereinbarung und sehen Sie sich die technische Dokumentation an unter api.cathopic.com/docs.

Das „Herunterladen“ von Bildern umfasst zwei Schritte: die Lizenzierung der Ressource mit /confirm und anschließend die Verwendung der zurückgegebenen URLs.

Schritt 1: Lizenzieren Sie die Ressource

Rufen Sie /confirm auf, um eine Ressource für einen bestimmten Endnutzer zu lizenzieren:

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

Parameter:

• media_id - Die Ressourcen-ID aus Ihren Suchergebnissen

• usage_type - Entweder „website“ oder „email“

• client_identifier - Eindeutige ID für Ihren Endnutzer

Schritt 2: Verwenden Sie die Download-URLs

Die Antwort enthält dauerhafte URLs in mehreren 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://..."
    }
  }
}

Wichtig: URLs speichern

Die zurückgegebenen URLs sind dauerhaft – speichern Sie sie in Ihrer Datenbank:

// Nach dem Aufruf von /confirm
const response = await api.confirm(mediaId, userId);
// In der Datenbank speichern
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// Beim nächsten Mal aus der DB abrufen, statt /confirm erneut aufzurufen

Das richtige Format wählen

AVIF-Format:

• Kleinere Dateigrößen (bessere Performance)

• Bessere Komprimierung

• Empfohlen für moderne Browser

• Nicht in älteren Browsern unterstützt

JPEG-Format:

• Universelle Kompatibilität

• Größere Dateigrößen

• Als Fallback für ältere Browser verwenden

Wichtige Erinnerung

⚠️ Prüfen Sie immer Ihre Datenbank, bevor Sie /confirm aufrufen. Wenn Sie es mehrfach für denselben Nutzer und dieselbe Ressource aufrufen, entstehen doppelte Gebühren.

Vollständige Dokumentation unter api.cathopic.com/docs.