Jak pobrać obrazy przez API?

Ważne doprecyzowanie: API nie umożliwia „pobierania” w tradycyjnym znaczeniu. Zamiast tego udostępnia stałe adresy URL do treści zoptymalizowanych pod WWW, które Twoja aplikacja wyświetla użytkownikom końcowym. Reguluje to Umowa licencyjna API.

Nie pobierasz plików

Działanie Cathopic API różni się zasadniczo od tradycyjnych pobrań:

• Brak transferu plików: Nigdy nie otrzymujesz ani nie przechowujesz samych plików obrazu/wideo

• Dostęp przez adresy URL: API udostępnia adresy URL wskazujące treści hostowane przez Cathopic

• Tylko pod WWW: Treści są serwowane w rozdzielczości odpowiedniej do wyświetlania cyfrowego

• Brak oryginalnych plików: Wysokiej jakości oryginały nigdy nie są dostępne przez API

• Zawsze hostowane: Treści pozostają na serwerach Cathopic lub na autoryzowanym CDN

Dostępne rozdzielczości

API udostępnia trzy rozmiary zoptymalizowane pod WWW:

• Small: Odpowiednie do miniatur i małych osadzeń (zwykle ok. 400 px szerokości)

• Medium: Dobre do standardowych treści w sieci (zwykle ok. 800 px szerokości)

• Large: Najlepsza jakość do wyświetlania w sieci (zwykle ok. 1200 px szerokości)

Krytyczne ograniczenia:

• Oryginalne pliki w wysokiej rozdzielczości są NIGDY udostępniane

• Rozdzielczości są zoptymalizowane do wyświetlania na ekranie, nie do druku

• Rozmiary plików są skompresowane dla szybkiej dostawy w sieci

• Nie możesz żądać niestandardowych rozdzielczości ani oryginalnej jakości

Aby poznać pełne warunki, przeczytaj całą Umowę licencyjną API i zapoznaj się z dokumentacją techniczną na api.cathopic.com/docs.

Pobieranie obrazów obejmuje dwa kroki: licencjonowanie zasobu przez /confirm, a następnie użycie zwróconych adresów URL.

Krok 1: Zlicencjonuj zasób

Wywołaj /confirm, aby zlicencjonować zasób dla konkretnego użytkownika końcowego:

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

Parametry:

• media_id - Identyfikator zasobu z wyników Twojego wyszukiwania

• usage_type - Albo „website”, albo „email”

• client_identifier - Unikalny identyfikator Twojego użytkownika końcowego

Krok 2: Użyj adresów URL do pobrania

Odpowiedź zawiera stałe adresy URL w wielu formatach:

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

Ważne: przechowuj adresy URL

Zwrócone adresy URL są stałe — przechowuj je w swojej bazie danych:

// Po wywołaniu /confirm
const response = await api.confirm(mediaId, userId);
// Zapisz w swojej bazie danych
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// Następnym razem pobierz z DB zamiast ponownie wywoływać /confirm

Wybór właściwego formatu

Format AVIF:

• Mniejsze rozmiary plików (lepsza wydajność)

• Lepsza kompresja

• Zalecany dla nowoczesnych przeglądarek

• Nieobsługiwany w starszych przeglądarkach

Format JPEG:

• Powszechna kompatybilność

• Większe rozmiary plików

• Użyj jako zamiennika dla starszych przeglądarek

Krytyczne przypomnienie

⚠️ Zawsze sprawdzaj swoją bazę danych przed wywołaniem /confirm. Wywołanie go wielokrotnie dla tego samego użytkownika i zasobu spowoduje utworzenie duplikatów opłat.

Pełna dokumentacja na api.cathopic.com/docs.