Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
8.5 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: GIFs
description: GIF search, featured and trending listings, search suggestions and share registration.
---

import RouteHeader from '@/components/RouteHeader.astro';

These routes search the instance's GIF provider. They need a session token. A bot token or OAuth2 bearer token gets 403 `ACCESS_DENIED`.

[Get instance discovery](/http-api/instance/#gif-provider-object) has a `gif` object that says whether the instance has a GIF provider.

## Provider headers

Every response from these routes has these headers when the instance has a GIF provider.

| Field | Type | Description |
| --- | --- | --- |
| X-Fluxer-GIF-Provider | string | The provider ID, such as `klipy` |
| X-Fluxer-GIF-Provider-Display-Name | string | The provider name to show |
| X-Fluxer-GIF-Provider-Attribution-Required | string | `true` when you must show the provider's attribution |

## GIF object

A GIF object is one result from the provider. [Save meme from URL](/http-api/memes/#save-meme-from-url) saves one to your collection.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| id<sup>1</sup> | string | The provider's identifier of the GIF |
| slug<sup>1</sup> | string | The canonical slug of the GIF |
| provider | string | The name of the provider (1-32 characters) |
| title | string | The title of the GIF |
| url | string | The provider page URL |
| src<sup>2</sup> | string | The direct media URL |
| proxy_src<sup>2</sup> | string | The [Media Proxy](/media-proxy/overview/) URL |
| width<sup>2</sup> | integer | The width in pixels |
| height<sup>2</sup> | integer | The height in pixels |
| media | map[string, [GIF media format](/http-api/memes/#gif-media-format-object) object] | The formats keyed by [format name](/http-api/memes/#gif-media-format-names) |
| placeholder?<sup>3</sup> | ?string | The thumbhash placeholder |

<sup>1</sup> Both have the same value

<sup>2</sup> From the `webm` entry of `media` when there is one, and from the first entry otherwise

<sup>3</sup> Always absent from the GIFs these routes return

### Example

```json
{
  "id": "goat-plays-banjo-4",
  "slug": "goat-plays-banjo-4",
  "provider": "klipy",
  "title": "Goat Plays Banjo",
  "url": "https://klipy.com/gifs/goat-plays-banjo-4",
  "src": "https://static.example.com/goat-plays-banjo.webm",
  "proxy_src": "https://media.example.com/external/9f21c0/goat-plays-banjo.webm",
  "width": 220,
  "height": 229,
  "media": {
    "webm": {
      "src": "https://static.example.com/goat-plays-banjo.webm",
      "proxy_src": "https://media.example.com/external/9f21c0/goat-plays-banjo.webm",
      "width": 220,
      "height": 229
    },
    "tinygif": {
      "src": "https://static.example.com/goat-plays-banjo-tiny.gif",
      "proxy_src": "https://media.example.com/external/4ad117/goat-plays-banjo-tiny.gif",
      "width": 137,
      "height": 90
    }
  }
}
```

## GIF category object

A category is a search term with a preview GIF. Send `name` as the `q` of [Search GIFs](#search-gifs) to get its GIFs.

### Structure

| Field | Type | Description |
| --- | --- | --- |
| name | string | The search term, translated for the locale |
| src<sup>1</sup> | string | The direct media URL of the preview |
| proxy_src<sup>1</sup> | string | The [Media Proxy](/media-proxy/overview/) URL of the preview |
| gif | ?[GIF](#gif-object) object | The preview GIF |

<sup>1</sup> The empty string when `gif` is null

## Deprecated vendor paths

These paths work like their successors and add `Deprecation`, `Link` and `Warning` headers.

| Method | Deprecated path | Successor |
| --- | --- | --- |
| GET | `/v1/tenor/search` | [Search GIFs](#search-gifs) |
| GET | `/v1/tenor/featured` | [Get featured GIFs](#get-featured-gifs) |
| GET | `/v1/tenor/trending-gifs` | [Get trending GIFs](#get-trending-gifs) |
| GET | `/v1/tenor/suggest` | [Get GIF search suggestions](#get-gif-search-suggestions) |
| POST | `/v1/tenor/register-share` | [Register a GIF share](#register-a-gif-share) |
| GET | `/v1/klipy/search` | [Search GIFs](#search-gifs) |
| GET | `/v1/klipy/featured` | [Get featured GIFs](#get-featured-gifs) |
| GET | `/v1/klipy/trending-gifs` | [Get trending GIFs](#get-trending-gifs) |
| GET | `/v1/klipy/suggest` | [Get GIF search suggestions](#get-gif-search-suggestions) |
| POST | `/v1/klipy/register-share` | [Register a GIF share](#register-a-gif-share) |

## Search GIFs

<RouteHeader method="GET" path="/v1/gifs/search" />

Returns at most 50 [GIF objects](#gif-object) matching a search term.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| q | string | The search term (1-256 characters) |
| locale? | string | A [supported locale](/topics/locales/#supported-locales), default `en-US` |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[GIF](#gif-object) object] | The matches |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when the instance has no GIF provider |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when the provider fails or times out |

The rate limit is 40 requests per 10 seconds, on the `gif:search` bucket.

## Get featured GIFs

<RouteHeader method="GET" path="/v1/gifs/featured" />

Returns a featured GIF and a list of category terms.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| locale? | string | A [supported locale](/topics/locales/#supported-locales), default `en-US` |

### Response body

| Field | Type | Description |
| --- | --- | --- |
| gifs | array[[GIF](#gif-object) object] | The featured GIF (0 or 1 items) |
| categories | array[[GIF category](#gif-category-object) object] | The categories (at most 50) |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The featured GIFs and categories |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when the instance has no GIF provider |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when the provider fails or times out |

The rate limit is 40 requests per 10 seconds, on the `gif:featured` bucket.

## Get trending GIFs

<RouteHeader method="GET" path="/v1/gifs/trending" />

Returns at most 50 trending [GIF objects](#gif-object).

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| locale? | string | A [supported locale](/topics/locales/#supported-locales), default `en-US` |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[[GIF](#gif-object) object] | The trending GIFs |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when the instance has no GIF provider |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when the provider fails or times out |

The rate limit is 40 requests per 10 seconds, on the `gif:trending` bucket.

## Get GIF search suggestions

<RouteHeader method="GET" path="/v1/gifs/suggest" />

Returns search term suggestions for a partial query.

### Query parameters

| Field | Type | Description |
| --- | --- | --- |
| q | string | The partial search term (1-256 characters) |
| locale? | string | A [supported locale](/topics/locales/#supported-locales), default `en-US` |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | array[string] | The suggestions |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when the instance has no GIF provider |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when the provider fails or times out |

The rate limit is 40 requests per 10 seconds, on the `gif:suggest` bucket.

## Register a GIF share

<RouteHeader method="POST" path="/v1/gifs/register-share" />

Tells the provider that a user sent one of its GIFs. Fluxer stores nothing.

### JSON body

| Field | Type | Description |
| --- | --- | --- |
| id | string | The `id` of the shared [GIF object](#gif-object) (1-300 characters) |
| q? | ?string | The search term that found the GIF (0-256 characters) |
| locale? | string | A [supported locale](/topics/locales/#supported-locales), default `en-US` |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 204 | empty | The provider accepted the registration |
| 403 | [error response](/http-api/#error-response) | `FEATURE_TEMPORARILY_DISABLED` when the instance has no GIF provider |
| 503 | [error response](/http-api/#error-response) | `SERVICE_UNAVAILABLE` when the provider fails or times out |

The rate limit is 60 requests per 10 seconds, on the `gif:register_share` bucket.