GIFs¶
A GIF is an animated media item from the instance's GIF provider. TEBHOS proxies search, trending, category and link-resolution requests to the provider and returns a compact GIF object with direct media URLs.
Every route requires a user session token (Authorization: Bearer <token>); a valid Bot <token> credential is rejected with 403 ACCESS_DENIED (an invalid one with 401 UNAUTHORIZED).
Provider availability¶
KLIPY is the only provider TEBHOS supports. Get instance discovery publishes it as the gif object:
attribution_required is true, so a client shows the KLIPY attribution mark next to GIF results.
An instance that has no provider key configured refuses every route on this page with 404 NOT_FOUND. gif_enabled in the instance services object reports whether the key is configured, unless an operator has overridden the flag, so a client that reads gif_enabled as true can still receive the 404.
A provider outage, an unreadable provider payload, or the internal GIF service not answering within 5 seconds returns 500 INTERNAL_SERVER_ERROR.
Locale and country¶
TEBHOS queries the provider with the fixed locale tr_TR and country TR. No route accepts a locale or country parameter.
Result freshness¶
The category list is cached for one hour, and resolved links are cached in memory. Search and trending results are fetched from the provider on every request.
GIF object¶
One media item the provider owns. Every URL in it resolves to bytes the provider hosts.
Structure¶
| Field | Type | Description |
|---|---|---|
| id | string | The provider-stable identifier of the GIF |
| title | string | The title the provider gives the GIF (may be empty) |
| url | string | The direct media URL a client sends or renders at full size. The first available of gif, mediumgif, tinygif |
| preview | string | The direct media URL of a small grid preview. The first available of tinygif, nanogif, gif, falling back to url |
| width | integer | The width of the preview format in pixels (200 when the provider reports none) |
| height | integer | The height of the preview format in pixels (200 when the provider reports none) |
| itemurl? | string | The provider page URL for the GIF (for example https://klipy.com/gifs/{slug}). Absent when the provider returned none |
A GIF has no snowflake and no creation timestamp. id is the provider's own identifier and does not sort by time.
Sending a GIF in a message
Post the GIF's itemurl as message content. Clients render a provider page link as the GIF by resolving it through Resolve a GIF link.
Example¶
{
"id": "goat-plays-banjo-4",
"title": "Goat Plays Banjo",
"url": "https://static.example.com/goat-plays-banjo.gif",
"preview": "https://static.example.com/goat-plays-banjo-tiny.gif",
"width": 137,
"height": 90,
"itemurl": "https://klipy.com/gifs/goat-plays-banjo-4"
}
GIF category object¶
Pairs a category search term with a preview image for that term.
Structure¶
| Field | Type | Description |
|---|---|---|
| searchterm | string | The search term the category stands for |
| name | string | The display name of the category, without a leading #. Falls back to searchterm |
| image | string | The direct URL of the category preview image (may be empty) |
To open a category, a client sends searchterm as the q of Search GIFs.
Search GIFs¶
GET /gifs/search
Searches the provider for GIFs matching a query. Returns at most 50 GIF objects in the order the provider returned them.
Query parameters¶
| Field | Type | Description |
|---|---|---|
| q | string | The search term. Leading and trailing whitespace is trimmed and the result must not be empty |
A term that matches nothing returns 200 with an empty array.
Response¶
| Status | Body | Condition |
|---|---|---|
| 200 | array[GIF object] | Results were returned, possibly as an empty array |
| 400 | error response | q is absent or blank (BAD_REQUEST) |
| 401 | error response | Missing or non-user credential |
| 404 | error response | The instance has no provider key configured (NOT_FOUND) |
| 500 | error response | The provider or the internal GIF service failed (INTERNAL_SERVER_ERROR) |
Rate limit¶
40 requests per 10 seconds for each client credential, on the gif:search bucket.
Get trending GIFs¶
GET /gifs/trending
Returns at most 50 of the provider's featured GIF objects.
Response¶
| Status | Body | Condition |
|---|---|---|
| 200 | array[GIF object] | Trending GIFs were returned, possibly as an empty array |
| 401 | error response | Missing or non-user credential |
| 404 | error response | The instance has no provider key configured (NOT_FOUND) |
| 500 | error response | The provider or the internal GIF service failed (INTERNAL_SERVER_ERROR) |
Rate limit¶
40 requests per 10 seconds for each client credential, on the gif:trending bucket.
Get GIF categories¶
GET /gifs/categories
Returns the provider's featured categories as an array of GIF category objects. Categories without a search term are dropped.
Response¶
| Status | Body | Condition |
|---|---|---|
| 200 | array[GIF category object] | Categories were returned, possibly as an empty array |
| 401 | error response | Missing or non-user credential |
| 404 | error response | The instance has no provider key configured (NOT_FOUND) |
| 500 | error response | The provider or the internal GIF service failed (INTERNAL_SERVER_ERROR) |
This route has no route-specific rate limit bucket; only the global limit applies.
Resolve a GIF link¶
GET /gifs/resolve
Resolves a provider page link into a GIF object. Clients use it to render a KLIPY link posted in a message as the GIF itself.
Query parameters¶
| Field | Type | Description |
|---|---|---|
| url | string | A provider page link of the form https://klipy.com/{kind}/{slug}, where kind is gif, gifs, clip or clips. http:// and a www. host prefix are accepted |
Response¶
| Status | Body | Condition |
|---|---|---|
| 200 | GIF object | The link was resolved |
| 400 | error response | url is absent or is not a recognised provider link (BAD_REQUEST) |
| 401 | error response | Missing or non-user credential |
| 404 | error response | The provider knows no GIF for the slug, or the instance has no provider key configured (NOT_FOUND) |
| 500 | error response | The provider or the internal GIF service failed (INTERNAL_SERVER_ERROR) |
This route has no route-specific rate limit bucket; only the global limit applies.
curl "https://tebhos.com/api/v1/gifs/resolve?url=https://klipy.com/gifs/goat-plays-banjo-4" \
-H "Authorization: Bearer $TEBHOS_TOKEN"
Not supported on TEBHOS
TEBHOS has no search-suggestion route, no share-registration route, no locale parameter, no provider response headers, and no vendor-named legacy path prefixes. GIF objects carry no Media Proxy URLs or format map.