API reference

Build it with an AI agent

Paste this into your coding agent (Claude Code, Cursor, Codex…). It points the agent at the integration guide for AI agents, which covers identification, attribution, previews, posting, errors and the picker's UX.

Add a GIF button to my Nostr app using the nostr.build GIF API.

Before writing any code, read https://gifs.nostr.build/llms.txt and the integration guide it links (https://gifs.nostr.build/developers/llms-full.txt), and follow the guide exactly: how my app identifies itself (Origin for web, API key from native code), the required "GIFs from nostr.build" attribution, the previews to show in the grid, posting the GIF's url with a NIP-92 imeta tag, and the error and rate-limit handling.

First tell me what you need from me (a registered origin or an API key from https://gifs.nostr.build/developers), then build it, and finish by going through the guide's "Before you call it done" checklist.

Authentication

Every request must identify a registered client. Browsers send an Origin header automatically. Native apps send Authorization: Bearer gnb_… with an API key, or a User-Agent that has been reviewed. Register your client.

Attribution

Show "GIFs from nostr.build", linked to https://nostr.build, wherever these GIFs appear — for example in your GIF picker's header.

GIFs from <a href="https://nostr.build" target="_blank" rel="noopener noreferrer">nostr.build</a>

Registering a client costs 1000 sats, once. The fee only keeps spam sign-ups out — it isn't profit and doesn't fund the site. It isn't refunded if you delete the client.

Animated previews and MP4

Every item links its original as url (post that in a note) and comes with smaller files to show while picking one.

previews.small.animated, previews.medium.animated

Animated WebP at a fixed height of 96 or 192 px, for grids. null when the GIF is too large to animate: show the still. For column grids use previews.w240 and previews.w480 instead: fitted to a width (at most 240 or 480 px, never enlarged), same shape.

previews.small.still, previews.medium.still

The first frame as PNG, same sizes. A poster while the animation loads, or the preview when there is none.

mp4

The animation as H.264 at its source size, many times smaller than the GIF. No audio and no loop flag, so play it muted and looping; transparency is shown on black. null for stills and past 60 s, 1800 frames or 4096 px.

<video src="…/mp4/orig/…" loop muted autoplay playsinline
  poster="…/still/192/…"></video>

An mp4 can still answer 404 when it is converted on first request and that fails: on the video's error event, fall back to the animated preview or url.

Endpoints

Schemas