Toju/agents-docs/features/klipy-gifs.md

Klipy GIFs

Status: Active Last updated: 2026-07-05

Overview

GIF search in chat and DM composers via a Klipy API proxy on the signaling server. API keys stay server-side; clients call same-origin routes on the active signal server.

Responsibilities

• Server: proxy/search Klipy API (variables.json klipyApiKey).
• Client chat domain: KlipyService, composer picker; DMs reuse the same integration.

API

GET /api/klipy/config

• Auth: Public
• Response: { enabled: boolean } — enabled when server has a configured API key

GET /api/klipy/gifs

• Auth: Public
• Query: q (search), page, per_page (default 24, max 50)
• Response: Normalised { gifs: [{ id, slug, title, url, previewUrl, width, height }], hasNext }
• Upstream: https://api.klipy.com/api/v1 with 8 s timeout

Client behavior

• GIF picker visibility is resolved against the current chat-server's signal server (not a global offline endpoint) so KLIPY availability matches the room's backend.
• Selected GIFs send as markdown image messages; rendering uses link-preview-media-proxy.md image proxy when needed.

Related

• server-directory.md — per-room signal server for config
• direct-messaging.md — DM composer reuse
• Domain README: toju-app/src/app/domains/chat/README.md

Changelog

Date	Change
2026-07-05	Initial Klipy proxy contract