---
name: og-image-generator
description: Turn an article URL or supplied title and subtitle into a 1200x630 Open Graph image and social metadata with TwitterShots templates. Use when a user asks to create an OG image, social preview, link preview, article cover, gradient title image, or agent-generated Open Graph metadata.
---

# TwitterShots OG Image Generator

Generate one deterministic social preview from a page URL or user-provided copy. Guide first-time users from API key setup directly into providing their content, make sensible visual defaults, call the API, and return the public image URL.

## Workflow

### 1. Check authentication, then prompt for content

POST requests require the same `X-API-KEY` used by other TwitterShots APIs.

If the user does not have a key:

1. Ask them to register or sign in at https://twittershots.com/api/auth/login?returnTo=/settings/keys.
2. Ask them to create a key at https://twittershots.com/settings/keys.
3. Ask them to save it as `TWITTERSHOTS_API_KEY` in their agent's secret manager or environment.
4. Continue after they confirm the key is configured.

Never print, repeat, log, or place the key in a URL. Do not ask the user to paste it into a public conversation when a secret store is available.

If the user pastes a key, do not quote it back. Use it only through a secret-capable header or environment mechanism and recommend moving it to `TWITTERSHOTS_API_KEY` for future requests. Never save it in the project, generated files, shell history, or source control.

As soon as the key is configured or validated, immediately tell the user what to do next. Use a prompt equivalent to:

> API key is ready. Send me the article or page URL for the OG image. If there is no URL, send the title and optional subtitle instead.

Do not stop after key validation or wait for the user to discover the next command.

### 2. Get the article content

Prefer an article or page URL as the input:

1. Ask for the URL if the user has not supplied content yet.
2. Read the accessible page and identify its main topic, headline, summary, site name, and category when present.
3. Rewrite the source into a clear OG title of at most 110 characters and a concise subtitle of at most 180 characters. Preserve the source's meaning; do not add unsupported claims.
4. If the page cannot be read, ask the user to provide the title and optional subtitle or paste the relevant article content.

If the user's input is not a URL, ask for the title and optional subtitle directly. When they provide longer source text, derive both from that text. Ask one concise follow-up only when the title remains genuinely ambiguous.

Before generation, briefly show the proposed title and subtitle. Continue without requiring another confirmation when they faithfully reflect the supplied source and the user did not ask to approve the copy first.

### 3. Choose the visual defaults

Use `openai-gradient` by default, with the `dreamlike` background and a `large` title. These are workflow defaults and must be sent explicitly because the API's own omitted-field defaults may differ.

Do not make a first-time user choose from every template or style before producing an image. Offer alternatives only when the user asks, the source clearly calls for another layout, or the subtitle must be visible in the image:

- Use `openai-gradient` for the default centered-title image over an OpenAI-inspired gradient. This layout emphasizes the title; the subtitle is not displayed on the image.
- Use `editorial` when the subtitle, site name, or category should be visible in the image.
- Use `gradient-title` when the user asks for a bold title-only image with a linear color gradient.
- Use `aurora-background` when the user asks for a soft aurora or mesh glow behind a centered title.

For `openai-gradient`, choose exactly one background: `dreamlike`, `blue`, `floral`, or `sky`. Use `dreamlike` unless the user requests a different look. Use `blue` for light text on a dark background; the other presets use dark text. Do not send arbitrary image URLs in this version.

For `gradient-title`, choose exactly one theme: `ocean`, `sunset`, `violet`, `midnight`, or `emerald`. Infer the closest theme from the user's visual direction; ask only when the choice materially matters. Do not invent custom gradient parameters in this version.

For `aurora-background`, choose exactly one aurora preset: `meadow`, `ember`, or `tide`. Use `meadow` unless the user requests a different look. Use `generated` only with three hex `colors` such as `#E9FF95,#59E39C,#2874F0`.

Use `titleSize: "large"` by default for `openai-gradient`, `gradient-title`, and `aurora-background`, increasing the title one preset step above the API's medium default. Step down to `medium` for long titles when needed for comfortable wrapping. Prefer `small` only for exceptionally long copy or when the user wants more negative space. Use `custom` only when the user requests an exact size, then send `fontSize` from 32 through 96.

### 4. Build the image inputs

Obtain a title before calling the API. Infer optional fields from the source when they are clear; otherwise omit them.

| Field | Required | Limit | Purpose |
|---|---:|---:|---|
| `title` | Yes | 110 characters | Main headline |
| `template` | No | enum | Skill default: `openai-gradient`; also `editorial`, `gradient-title`, or `aurora-background` |
| `theme` | No | enum | Gradient preset; default `ocean` |
| `background` | No | enum | OpenAI gradient image; default `dreamlike` |
| `aurora` | No | enum | Aurora preset; default `meadow` |
| `colors` | No | 3 hex colors | Used when `aurora` is `generated` |
| `titleSize` | No | enum | `small`, `medium`, `large`, or `custom`; skill default `large` |
| `fontSize` | No | 32–96 | Pixel size used when `titleSize` is `custom` |
| `description` | No | 180 characters | Editorial supporting summary |
| `siteName` | No | 40 characters | Optional editorial brand; omitted or empty values stay hidden |
| `category` | No | 32 characters | Optional editorial label; omitted or empty values stay hidden |
| `accent` | No | `#RRGGBB` | Editorial accent color |

Do not invent `siteName` or `category`. Send them only when the user or source page provides them. Omit either field when it is unknown or intentionally removed; the renderer must not add fallback labels.

### 5. Generate the image

Send a POST request and request the default JSON response:

```bash
curl --fail-with-body --silent --show-error \
  https://twittershots.com/api/og-image \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $TWITTERSHOTS_API_KEY" \
  -d '{
    "title": "Free OG Generator for AI Agents",
    "template": "openai-gradient",
    "background": "dreamlike",
    "titleSize": "large"
  }'
```

Use the agent's HTTP tool instead of curl when appropriate. Send the same URL, header, and JSON body. The machine-readable API definition is available at https://twittershots.com/og-image-openapi.yaml.

### 6. Verify and return the result

Read `imageUrl`, `width`, `height`, `alt`, `template`, `theme`, `background`, `titleSize`, `fontSize`, and `metadata` from the JSON response. Confirm the image URL returns `200` with `image/png` when the agent can make a follow-up request.

Return:

- the generated image or clickable `imageUrl`;
- the alt text;
- the returned Open Graph and Twitter metadata;
- a brief note that the image is 1200x630.

Then offer one short next action, such as changing the title, showing the subtitle with the editorial template, or trying another gradient. Do not make the user restart the authentication flow for an iteration in the same session.

Do not expose the API key in the response. The returned GET image URL is intentionally public so social crawlers can fetch it without authentication.

## Errors

- `400`: Correct invalid or overlong fields, then retry once.
- `401`: Ask the user to configure `TWITTERSHOTS_API_KEY`.
- `403`: Ask the user to replace an invalid or inactive key at https://twittershots.com/settings/keys.
- `503`: Report that authentication is temporarily unavailable and suggest retrying later.

Do not repeatedly retry authentication errors.