Hogyan tölthetek le képeket API-n keresztül?

Fontos pontosítás: Az API nem teszi lehetővé a „letöltést” a hagyományos értelemben. Ehelyett tartós (permanens) URL-eket ad olyan, webre optimalizált tartalomhoz, amelyet az alkalmazásod a végfelhasználóknak szolgál ki. Ennek feltételeit a API License Agreement szabályozza.

NEM töltesz le fájlokat

A Cathopic API alapvetően másképp működik, mint a hagyományos letöltések:

• Nincs fájlátvitel: Soha nem kapod meg és nem tárolod a tényleges kép/videó fájlokat

• URL-alapú hozzáférés: Az API olyan URL-eket ad, amelyek a Cathopic által hosztolt tartalomra mutatnak

• Csak webre optimalizált: A tartalom olyan felbontásban kerül kiszolgálásra, amely digitális megjelenítésre alkalmas

• Nincsenek eredeti fájlok: A nagy felbontású eredetik soha nem érhetők el API-n keresztül

• Mindig hosztolt: A tartalom a Cathopic szerverein vagy egy engedélyezett CDN-en marad

Elérhető felbontások

Az API három webre optimalizált méretet biztosít:

• Kis méret: Alkalmas miniatűrökhez és kis beágyazásokhoz (jellemzően ~400 px széles)

• Közepes méret: Jó általános webes tartalomhoz (jellemzően ~800 px széles)

• Nagy méret: A legjobb minőség webes megjelenítéshez (jellemzően ~1200 px széles)

Fontos korlátozások:

• A nagy felbontású eredeti fájlokkal SOHA nem szolgálunk

• A felbontások képernyőmegjelenésre vannak optimalizálva, nem nyomtatásra

• A fájlméretek tömörítettek a gyors webes kézbesítéshez

• Nem kérhetsz egyedi felbontásokat vagy eredeti minőséget

A teljes feltételekért olvasd el a teljes API License Agreement dokumentumot, és tekintsd át a technikai dokumentációt itt: api.cathopic.com/docs.

A képek letöltése két lépésből áll: a forrás licencelése a /confirm segítségével, majd a visszaadott URL-ek használata.

1. lépés: Licenceld a forrást

Hívd meg a /confirm metódust egy adott végfelhasználó számára történő licenceléshez:

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

Paraméterek:

• media_id - A keresési találatokból származó forrásazonosító

• usage_type - „website” vagy „email”

• client_identifier - A végfelhasználód egyedi azonosítója

2. lépés: Használd a letöltési URL-eket

A válasz több formátumban tartalmaz tartós URL-eket:

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

Fontos: Tárold az URL-eket

A visszaadott URL-ek tartósak – tárold őket az adatbázisodban:

// Miután meghívtad a /confirm-et
const response = await api.confirm(mediaId, userId);
// Tárold az adatbázisban
await db.save({
  userId: userId,
  mediaId: mediaId,
  avifUrls: response.download_url.avif,
  jpegUrls: response.download_url.jpeg,
  licensedAt: new Date()
});
// Legközelebb az adatbázisból vedd ki, ne hívd meg újra a /confirm-et

A megfelelő formátum kiválasztása

AVIF formátum:

• Kisebb fájlméretek (jobb teljesítmény)

• Jobb tömörítés

• Ajánlott a modern böngészők számára

• Nem támogatott a régebbi böngészőkben

JPEG formátum:

• Általános kompatibilitás

• Nagyobb fájlméretek

• Használd tartalékként a régebbi böngészők esetén

Fontos emlékeztető

⚠️ Mindig ellenőrizd az adatbázisodat, mielőtt meghívnád a /confirm-et. Ha ugyanarra a felhasználóra és forrásra többször is meghívod, az duplikált díjakat eredményez.

Teljes dokumentáció: api.cathopic.com/docs.