REST API V2
REST API zdarma nad vším, co tu hostujeme: vyhledávání, populární, kategorie, našeptávač a hlášení sdílení. Bez registrační zdi a bez placeného tarifu.
Tvar odpovědi přesně odpovídá starému v2 GIF API, kterému už umí rozumět velká část existujících klientů, a to včetně jeho zvláštností: flags je řetězec oddělený čárkami, created je desetinné číslo v unixových sekundách a formát, který nemáme, v media_formats úplně chybí, místo aby přišel jako null. Pokud tvoje aplikace 30. června 2026 přestala fungovat, celá migrace je většinou jen změna základní adresy.
Jeden request, žádná registrace. Společný demo klíč níž funguje hned a je omezený na 2 requesty za sekundu a 2000 za den.
curl "https://gifs.appmaxx.io/api/v2/search?q=excited+cat&limit=8&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
Klíč posílej buď jako parametr key, nebo jako hlavičku Authorization: Bearer. Klíč vypadá jako amxg_ a 40 znaků: prvních 8 je veřejný prefix, který klíč identifikuje, zbylých 32 je tajná část. Ukládáme jenom hash celého klíče, takže ztracený klíč nejde obnovit, jen vydat nový.
curl -H "Authorization: Bearer amxg_demokey0publicdemokeyforgifsappmaxxio000" \ "https://gifs.appmaxx.io/api/v2/featured?limit=8"
Je veřejný záměrně. Hodí se na zkoušení a do příkladů, ne do aplikace s uživateli.
Pro vlastní klíč s reálnými limity napiš na ahoj@appmaxx.io jméno aplikace a přibližný počet requestů za den. Je to zdarma.
API nikdy nečte cookies a nepoužívá tvoje přihlášení. Právě proto se dá volat z jakékoli domény.
Platí dva limity: krátkodobý limit za sekundu a denní kvóta, která přežije restart. Každá úspěšná odpověď říká, jak na tom jsi.
Čtecí endpointy odpovídají s public, max-age=60, s-maxage=300, takže cache před tvojí aplikací tě nestojí nic z kvóty. registershare se necachuje nikdy.
/api/v2/searchFulltextové vyhledávání tolerantní k překlepům, řazené podle relevance a pak podle popularity. Vyžaduje q.
curl "https://gifs.appmaxx.io/api/v2/search?q=excited+cat&limit=8&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
/api/v2/featuredFeed populárních GIFů. Bez dotazu.
curl "https://gifs.appmaxx.io/api/v2/featured?limit=8&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
/api/v2/categoriesProhlížitelné kategorie, každá s reprezentativním obrázkem. Klíč obálky je tags.
curl "https://gifs.appmaxx.io/api/v2/categories?type=featured&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
/api/v2/autocompleteDoplňování rozepsaného dotazu, pro vyhledávací pole.
curl "https://gifs.appmaxx.io/api/v2/autocomplete?q=exc&limit=5&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
/api/v2/search_suggestionsSouvisející výrazy k dotazu, který uživatel už dopsal, pro řádek štítků pod výsledky.
curl "https://gifs.appmaxx.io/api/v2/search_suggestions?q=cat&limit=5&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
/api/v2/trending_termsCo lidé hledají právě teď.
curl "https://gifs.appmaxx.io/api/v2/trending_terms?limit=10&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
/api/v2/postsDohledání id, která sis uložil, ve stejném pořadí, v jakém je pošleš. Id, která už neexistují, se přeskočí a dávka kvůli nim neselže.
curl "https://gifs.appmaxx.io/api/v2/posts?ids=1J8QK2M4KDR7&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
/api/v2/registershareŘekni nám, že uživatel GIF skutečně sdílel. Nic tě to nestojí a je to nejsilnější signál pro řazení, který máme, takže to prosím posílej.
curl "https://gifs.appmaxx.io/api/v2/registershare?id=1J8QK2M4KDR7&q=excited+cat&key=amxg_demokey0publicdemokeyforgifsappmaxxio000"
Seznamové endpointy vracejí obálku s next a results. Hodnotu next pošli zpátky jako pos pro další stránku a skonči, až bude prázdný řetězec, který dostaneš místo null. Kurzory jsou podepsané a vázané na dotaz, který je vytvořil, takže kurzor použitý na jiný dotaz skončí čistou chybou 400, a ne stránkou nesouvisejících výsledků.
Dva endpointy se záměrně odchylují, protože stejně to dělalo i API, které nahrazujeme: categories vrací tags místo results a posts nevrací next vůbec.
Tři endpointy pro výrazy vracejí ploché pole řetězců, ne objekty odpovědi.
{
"next": "eyJvIjo4LCJrIjpudWxsLCJwIjoxLCJoIjoiOTFmMiJ9.qN0m1c8Y",
"results": [
{
"id": "1J8QK2M4KDR7",
"title": "excited cat",
"content_description": "orange cat vibrating with excitement",
"media_formats": {
"gif": {
"url": "https://gifs.appmaxx.io/m/ab/cd/<hash>/gif.gif",
"dims": [498, 372],
"duration": 2.4,
"size": 812344,
"preview": "https://gifs.appmaxx.io/m/ab/cd/<hash>/preview.webp"
},
"tinygif": {
"url": "https://gifs.appmaxx.io/m/ab/cd/<hash>/tinygif.gif",
"dims": [220, 164],
"duration": 2.4,
"size": 98213,
"preview": "https://gifs.appmaxx.io/m/ab/cd/<hash>/preview.webp"
},
"mp4": {
"url": "https://gifs.appmaxx.io/m/ab/cd/<hash>/mp4.mp4",
"dims": [498, 372],
"duration": 2.4,
"size": 141002,
"preview": "https://gifs.appmaxx.io/m/ab/cd/<hash>/preview.webp"
}
},
"created": 1785283200.0,
"hasaudio": false,
"hascaption": false,
"flags": "",
"bg_color": "#1e1e1e",
"tags": ["cat", "excited"],
"itemurl": "https://gifs.appmaxx.io/g/excited-cat-1J8QK2M4KDR7",
"url": "https://gifs.appmaxx.io/g/1J8QK2M4KDR7"
}
]
} Každý klíč níž je v media_formats tehdy, když danou variantu máme, a jinak tam není. Přes media_filter si vyžádej jen podmnožinu a odpovědi zůstanou malé.
Chyby používají stejnou obálku jako API, které nahrazujeme, takže existující ošetření chyb funguje dál. Pole details je vždycky přítomné a vždycky prázdné.
{
"error": {
"code": 429,
"message": "Daily quota exceeded: 2000 requests per day",
"status": "RESOURCE_EXHAUSTED",
"details": []
}
} Nasměruj klienta na základní adresu výš a vyměň klíč. Jeden rozdíl je dobré znát: naše id jsou neprůhledné alfanumerické řetězce, ne čísla, takže kód, který id parsuje jako celé číslo, potřebuje opravit. Jména endpointů, parametrů a polí jsou jinak stejná, registershare včetně.
K dispozici je i oEmbed provider na /api/oembed pro všechno, co umí oEmbed, tedy třeba Slack, WordPress nebo Discourse. Adresu stránky se sdílením pošli jako url. Klíč nepotřebuje.