> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamonster.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Open Graph images for your site

> Give every page its own share picture with an instant link: a URL that draws a template from its query string, signed on your server, rendered once and cached.

When a page is shared on Slack, LinkedIn, X or iMessage, the platform shows the picture in its `og:image` tag. An **instant link** makes that picture from a [template](https://docs.mediamonster.app/templates.md), with the page's own words in it, from nothing but a URL:

```
https://mediamonster.dev/i/k3v9x2m4q8w1z7ab.png?title=How+we+cut+a+2-hour+episode&site=latebite.fm&s=…
```

The first request for a set of words renders the picture and keeps it. Every request after that is served from storage.

## How it works

* **One template per link.** A link draws one of your workspace's templates, or a built-in. [Link preview](https://docs.mediamonster.app/templates.md#built-in-templates) (`og-card`) is 1200 × 630, the size platforms ask for.
* **Fields go in the query string.** Each field of the template is a parameter named after it: `?title=…&byline=…`. A field you leave out keeps the template's own words. Parameters that aren't fields are ignored, and listed in the `x-mediamonster-ignored` header.
* **The extension is the format.** `.png`, `.jpg` or `.webp`.
* **`size` is optional.** `size=1080x1080` draws it at another size the template is laid out for, or one of 1080x1080, 1080x1350, 1080x1920, 1920x1080 and 1200x630.
* **Only new pictures cost.** A new set of words costs 1 credit, the price of one [Fill a template](https://docs.mediamonster.app/skills/reference/fill-template.md). A picture the link has made before is free, however often it's loaded. Requests for the same new picture at the same moment wait for one drawing, and it's billed once. It's billed to the link's workspace.
* **It's cached for good.** A picture comes back with `Cache-Control: public, max-age=31536000, immutable`. The URL names the picture exactly, so the same URL always gets the same picture.

## Make a link

1. Open the template at [mediamonster.app/templates](https://mediamonster.app/templates).
2. Press **Get a link**, then **New link**.
3. Leave **Signed URLs only** picked, set any limits, and press **Make link**.
4. Copy the **secret**. It's shown once.

Owners, admins and members can make links. Viewers can see them.

| Setting | What it does |
| - | - |
| **Who can make pictures** | Signed URLs only, or anyone with the link. See [Open links](#open-links). |
| **New pictures per address, per hour** | How many new pictures one address can make in an hour. Pictures already made don't count. |
| **Most pictures in all** | How many new pictures the link can ever make. After that it answers `403` for new ones, and the ones it made still load. |
| **Switch off on** | A date the link stops answering. |
| **Pin to version** | For a saved template: keep drawing this version when the template changes. Left off, the link follows the latest version, and a change makes new pictures. |

You can also make one over the API:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/instant-links \
  -H "Authorization: Bearer $MEDIAMONSTER_KEY" \
  -H "content-type: application/json" \
  -d '{"template": "og-card", "most_renders": 5000}'
```

The answer carries `secret` and an `example_url` that works. `GET /api/v1/instant-links` lists your links and `DELETE /api/v1/instant-links/{id}` deletes one. Making a link needs a live key with the `run` scope.

## Sign each URL on your server

Keep the secret in your server's environment, never in a page or a repository. Sign each URL where the page is rendered, with the SDK:

```ts Node theme={"theme":{"light":"github-dark","dark":"github-dark"}}
import { instantLinkUrl } from "@mediamonster/sdk";

const image = await instantLinkUrl(
  "https://mediamonster.dev/i/k3v9x2m4q8w1z7ab.png",
  { title: post.title, byline: `${post.author} · ${post.minutes} min read` },
  process.env.MEDIAMONSTER_LINK_SECRET,
);
```

```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
import os
from mediamonster.instant_links import instant_link_url

image = instant_link_url(
    "https://mediamonster.dev/i/k3v9x2m4q8w1z7ab.png",
    {"title": post.title, "byline": f"{post.author} · {post.minutes} min read"},
    os.environ["MEDIAMONSTER_LINK_SECRET"],
)
```

Then put it in the page's head:

```html theme={"theme":{"light":"github-dark","dark":"github-dark"}}
<meta property="og:image" content="{{ image }}" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="{{ image }}" />
```

### Signing without the SDK

`s` is HMAC-SHA256, written as lower-case hex, under the link's secret, of this text:

```
<path>?<query>
```

* `<path>` is the URL's path: `/i/k3v9x2m4q8w1z7ab.png`.
* `<query>` is every parameter except `s`, sorted by name, each name and value escaped as JavaScript's `encodeURIComponent` does (Python: `quote(v, safe="-_.!~*'()")`), joined with `&`.
* With no parameters, the text still ends in `?`.

Add the result as `s`. The order you write the query in doesn't matter. Each parameter can appear once.

## Open links

An open link answers any query with no signature, so a static site with no server can use it. Anyone who has the link can make new pictures with any words in them, and each one costs your workspace 1 credit. So an open link is only made when you pick **Anyone with the link**, and it's always held to a limit per address (30 an hour when you don't set one). Set **Most pictures in all** as well.

## Pictures in fields

A picture field takes a link to a JPEG, PNG, WebP or GIF, starting `https://`. It's fetched once, when the picture is first drawn.

If the link doesn't load, the picture is still drawn: the field falls back to the template's own picture, or is left out. The response says which fields in the `x-mediamonster-missing` header, and is cached for 5 minutes instead of a year, so the real picture is drawn once the link answers again. A picture from the Vault's own CDN link isn't fetched this way yet.

## When it doesn't answer with a picture

A refusal is plain text with its code in the `x-mediamonster-error` header, and it's never cached.

| Status | Code | When |
| - | - | - |
| `400` | `bad_query` | A `size` the template isn't laid out for, a value over 2,000 characters, or a parameter sent twice |
| `402` | `insufficient_credits` | The workspace is out of credits. Pictures made before still load |
| `403` | `missing_signature`, `bad_signature` | A signed link without `s`, or with one that doesn't match |
| `403` | `most_renders` | The link has made all the pictures it's allowed to |
| `404` | `not_found` | No link with that id, or it's switched off |
| `404` | `template_gone` | The template was deleted |
| `410` | `link_expired` | Past the link's date |
| `429` | `rate_limited` | Too many new pictures from one address. `Retry-After` says when |
| `502` | `render_failed` | The picture couldn't be drawn. Its credit went back |
| `503` | `render_busy` | Another request is still drawing the same picture. `Retry-After` says when |

Out of credits is a `402`, not a picture that says so. Platforms keep the first picture they get for a page for days, so a picture of an error would stay on your link previews long after you top up. A `402` isn't kept, and the next time the platform asks it gets the real picture.

## Switch off, rotate or delete

Under **Get a link**:

* **The switch** stops a link answering. Turn it back on and its URLs work again.
* **New secret** gives a signed link a new secret. Every URL signed with the old one stops working at once, so sign them again.
* **Delete** removes the link for good.

Pictures a browser or a platform has already cached are theirs to keep, whichever you do.

Making, changing, rotating and deleting a link each shows on the workspace's [activity](https://docs.mediamonster.app/account/settings.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.