---

API Quickstart Guide

The examples below directly target the GIPHY-compatible layer exposed on `https://heypster-gif.com/giphy`. Routes are protected by the `giphy.apikey` middleware; if your implementation mirrors GIPHY, continue to send `api_key`.

1. Test a search request

curl "https://heypster-gif.com/giphy/v1/gifs/search?api_key=YOUR_HEYPSTER_API_KEY&q=party&limit=12&lang=en"

2. Do the same in JavaScript

const HEYPSTER_API_HOST = 'https://heypster-gif.com/giphy';
const HEYPSTER_API_KEY = 'YOUR_HEYPSTER_API_KEY';

async function searchGifs(query) {
    const response = await fetch(
        `${HEYPSTER_API_HOST}/v1/gifs/search?api_key=${HEYPSTER_API_KEY}&q=${encodeURIComponent(query)}&limit=12&lang=en`
    );

    const payload = await response.json();
    return payload.data;
}

3. Use the same renditions as GIPHY

const gif = payload.data[0];

const originalUrl = gif.images.original.url;
const originalMp4 = gif.images.original.mp4;
const originalWebp = gif.images.original.webp;
const fixedWidthUrl = gif.images.fixed_width.url;
const previewGif = gif.images.preview_gif.url;

4. Other available endpoints

# Categories
curl "https://heypster-gif.com/giphy/v1/gifs/categories?api_key=YOUR_HEYPSTER_API_KEY"

# Trending searches
curl "https://heypster-gif.com/giphy/v1/trending/searches?api_key=YOUR_HEYPSTER_API_KEY"

# Random ID
curl "https://heypster-gif.com/giphy/v1/randomid?api_key=YOUR_HEYPSTER_API_KEY"

# Emoji variations
curl "https://heypster-gif.com/giphy/v2/emoji/1/variations?api_key=YOUR_HEYPSTER_API_KEY"

---

GIF Endpoints

The structure below follows the same reading flow as GIPHY docs: each endpoint keeps a familiar REST path and a contract designed to reduce refactoring.

---

Response Schema

For a smooth migration, keep your parsing logic focused on these four blocks.

{
  "data": [
    {
      "id": "abc123",
      "title": "celebration",
      "url": "https://your-heypster-app/gifs/abc123",
      "slug": "celebration-abc123",
      "rating": "g",
      "images": {
        "original": {
          "url": "https://cdn.heypster.example/original-mini.gif",
          "width": "",
          "height": "",
          "mp4": "https://cdn.heypster.example/original.mp4",
          "webp": "https://cdn.heypster.example/original-mini.gif"
        },
        "fixed_width": {
          "url": "https://cdn.heypster.example/fixed_width.gif",
          "width": "",
          "height": "",
          "mp4": "https://cdn.heypster.example/fixed_width.mp4",
          "webp": "https://cdn.heypster.example/fixed_width.gif"
        },
        "preview_gif": {
          "url": "https://cdn.heypster.example/preview.gif"
        },
        "preview": {
          "mp4": "https://cdn.heypster.example/preview.mp4"
        }
      }
    }
  ],
  "pagination": {
    "total_count": 500,
    "count": 25,
    "offset": 0
  },
  "meta": {
    "status": 200,
    "msg": "OK",
    "response_id": "heypster-response-id"
  }
}

---

Best Practices

• Keep your existing GIPHY parser as long as your app mostly reads `data`, `pagination`, `meta`, and `images`.
• `pagination` is not present on every endpoint: single-object and some utility endpoints only return `data` and `meta`.
• Request only the renditions you actually need to reduce bandwidth on web and mobile.
• On Heypster, image renditions are rebuilt from `gif_mini` and video renditions from `h264`.
• Do not depend on `webm`: the current contract exposes `webp` and `mp4`.
• Keep `limit` and `offset` client-side to preserve identical pagination behavior during migration.
• Cache suggestions and trending feeds server-side if your traffic or quota profile requires it.