Media Attachments Metadata (imeta)

1 Overview

A Nostr note carries media the simple way: the author pastes a URL into the event content. A bare URL tells the client nothing else. The client does not know the file type, the image size, or a text alternative. It must download the file before it can lay out the post.

This NIP fixes that with the imeta tag. The name means inline metadata. A client adds media attachments — images, videos, and other files — by including a URL in the event content, along with a matching imeta tag. The tag describes that URL: MIME type, dimensions, a blurhash placeholder, a file hash, alt text, and fallback URLs.

imeta tags MAY add information about media URLs in the event's content. Each imeta tag SHOULD match a URL in the event content. Clients MAY replace imeta URLs with rich previews. The tag reuses the field vocabulary of NIP-94, so one set of field names serves both file events and inline attachments.

2 The imeta Tag

The imeta tag is variadic: it has no fixed length. Each entry after the tag name is one space-delimited key/value pair inside a single string. The key is the first word. The value is the rest of the string.

[
  "imeta",
  "url <media URL, required>",
  "<field> <value>",   // one entry per field, at least one
  ...
]

Four normative rules govern the tag:

1. Each imeta tag MUST have a url entry and at least one other field.
2. An imeta tag MAY include any field specified by NIP-94.
3. Each imeta tag SHOULD match a URL in the event content.
4. There SHOULD be only one imeta tag per URL.

The fields below appear in the specification's own example. All of them come from the NIP-94 vocabulary:

3 Recommended Client Behavior

The metadata is produced at composition time. The spec recommends two paths:

• Upload path. The user uploads a file during a new post. The client MAY include this metadata after the file is uploaded and included in the post.
• Paste path. The user pastes a URL during post composition. The client MAY download the file and add this metadata before the post is sent.

On the reading side, a client MAY replace imeta URLs in the content with rich previews. A client MAY ignore imeta tags that do not match the URL in the event content. Every rule in this NIP is a MAY or a SHOULD: an event without imeta tags is still valid, and a client without imeta support still renders the bare URL.

4 Worked Example

The event below is a plain kind-1 note (NIP-10). The content holds one image URL. One imeta tag matches it and carries seven metadata entries, including two fallback URLs.

{
  "id": "7fa8c2e1d0…",
  "pubkey": "22a12a12…",
  "created_at": 1749762600,
  "kind": 1,
  "content": "More image metadata tests, do not mind me https://nostr.build/i/my-image.jpg",
  "tags": [
    [
      "imeta",
      "url https://nostr.build/i/my-image.jpg",
      "m image/jpeg",
      "blurhash eVF$^OI:${M{o#*0-nNFxakD-?xVM}WEWB%iNKxvR-oetmo#R-aen$",
      "dim 3024x4032",
      "alt A scenic photo overlooking the coast of Costa Rica",
      "x <sha256 hash as specified in NIP-94>",
      "fallback https://nostrcheck.me/alt1.jpg",
      "fallback https://void.cat/alt1.jpg"
    ]
  ],
  "sig": "e8551d85…"
}

A rendering client walks through the event like this:

1. Scan the content. Find the URL https://nostr.build/i/my-image.jpg.
2. Find the imeta tag whose url entry matches that URL.
3. Reserve a 3024x4032 box from dim. Paint the blurhash placeholder into it.
4. Fetch the image. If the primary URL fails, try each fallback URL in turn.
5. Check the download against the x hash. Swap the placeholder for the image.
6. Set the alt text on the rendered image. Replace the raw URL in the text with the rich preview.

5 Version History

The imeta tag started life under the number 29 and moved to 92 three months later. Notable changes, newest first:

• 20262026-06Title settled as "Media Attachments Metadata (imeta)" after two renames for clarity.
• 20252025-01Lowercase "may" became normative MAY for adding metadata, using NIP-94 fields, and rich previews.
• 20242024-02Added the rule that clients MAY ignore imeta tags that do not match a content URL.
• 20242024-02Renumbered from NIP-29 to NIP-92; the old number later went to relay-based groups (NIP-29).
• 20242024-02Scope widened from images to all files; "MUST match URLs" softened to SHOULD; m added to the example.
• 20242024-02Typo fixes: URL casing and a missing comma in the example.
• Origin2023-11Jon Staab added the imeta tag as draft NIP-29, "Add imeta tag".

6 See Also

• NIP-01 — the base event and tag format that imeta rides on.
• NIP-94 — defines the field vocabulary (m, dim, x, blurhash, …) that imeta borrows.
• NIP-68 — picture-first feeds; picture events build on imeta.
• NIP-71 — video events with the same metadata style.
• NIP-96 — HTTP file storage servers that return this metadata at upload time.