---
name: og-image-generator
description: Generate a 1200x630 Open Graph image and social metadata with TwitterShots templates and curated gradient themes. 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 page metadata. Guide the user through authentication, collect only the missing inputs, call the API, and return the public image URL.

## Workflow

### 1. Check authentication

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.

### 2. Collect the image inputs

Obtain a title before calling the API. Infer optional fields from the user's page or article when they are clear; otherwise ask one concise follow-up question.

| Field | Required | Limit | Purpose |
|---|---:|---:|---|
| `title` | Yes | 110 characters | Main headline |
| `template` | No | enum | `editorial` (default) or `gradient-title` |
| `theme` | No | enum | Gradient preset; default `ocean` |
| `description` | No | 180 characters | Editorial supporting summary |
| `siteName` | No | 40 characters | Editorial brand or publication |
| `category` | No | 32 characters | Editorial label such as Guide or Product |
| `accent` | No | `#RRGGBB` | Editorial accent color |

Choose the template from the requested content structure:

- Use `editorial` when the user needs a title, summary, site name, and category.
- Use `gradient-title` when the user wants a bold title-only image with a gradient background.

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.

### 3. 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": "How to ship better social previews",
    "template": "gradient-title",
    "theme": "violet"
  }'
```

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.

### 4. Verify and return the result

Read `imageUrl`, `width`, `height`, `alt`, `template`, `theme`, 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.

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.