# ThumbnailCreator for AI agents

ThumbnailCreator makes YouTube thumbnails with AI. These steps let you, an AI agent, create an account for your human, buy credits, and make thumbnails for them.

- MCP server (streamable HTTP): `https://www.thumbnailcreator.com/mcp`
- REST API: `https://www.thumbnailcreator.com/api/v1` (Bearer API key)
- Human-readable version of this page: https://www.thumbnailcreator.com/agents

## 1. Connect the MCP server

Connect without a key first. Signup tools work unauthenticated.

```bash
claude mcp add --transport http thumbnailcreator https://www.thumbnailcreator.com/mcp
```

Other clients: add a streamable HTTP server with URL `https://www.thumbnailcreator.com/mcp`.

If you can't use MCP, every step below has a REST equivalent (see "REST API").

## 2. Get an API key (needs your human once)

1. Call `start_signup` with your human's email and your name as `agent_name`. They get an email with an 8-character code like `K7QM-4XPA`.
2. Ask them for the code. Don't guess it and don't read their inbox unless they asked you to.
3. Call `verify_signup` with the email and code. If the email is new, an account is created. Otherwise the agent connects to their existing account. You get back an API key (`api_…`) once. Save it somewhere secure, like your secret store or MCP config, never in chat logs or a repo.
4. Reconnect the MCP server with the key:

```bash
claude mcp remove thumbnailcreator
claude mcp add --transport http thumbnailcreator https://www.thumbnailcreator.com/mcp --header "Authorization: Bearer <api_key>"
```

```json
{
  "mcpServers": {
    "thumbnailcreator": {
      "url": "https://www.thumbnailcreator.com/mcp",
      "headers": {
        "Authorization": "Bearer <api_key>"
      }
    }
  }
}
```

The `x-api-key: <api_key>` header also works.

## 3. Buy credits (your human pays)

New accounts start with 0 credits. Call `list_credit_packs`, pick a pack with your human, then call `buy_credits`. It returns a Stripe Checkout link. Give the link to the human, who pays on Stripe; you never handle card details. Credits arrive a few seconds after payment. Confirm with `get_account`.

| Pack | Credits | Price | Per credit |
| --- | --- | --- | --- |
| `pack_10` | 10 | $5 | $0.50 |
| `pack_25` | 25 | $10 | $0.40 |
| `pack_50` | 50 | $19 | $0.38 |
| `pack_100` | 100 | $35 | $0.35 |
| `pack_250` | 250 | $79 | $0.32 |
| `pack_1000` | 1000 | $250 | $0.25 |
| `pack_3000` | 3000 | $600 | $0.20 |

Subscriptions (monthly credits and more features) are at https://www.thumbnailcreator.com/pricing.

## 4. Make thumbnails

- **From a YouTube video (best):** call `create_video_thumbnails` with `youtube_url` and `variant_count` (1, 4, 8 or 12; 1 credit each). Then call `get_video_thumbnails` every 20-30 seconds until `status` is `COMPLETED`. A set usually takes 2-4 minutes, and a failed job refunds its credits.
- **From a prompt:** call `generate_thumbnail` (1 credit, up to about a minute). Keep on-image text to 2-4 words.
- **Edit:** call `edit_thumbnail` with `thumbnail_id` and an instruction (1 credit).
- **Personalise:** `list_assets` returns face, style and brand ids. Faces are trained in the web app, and only active ones can be used.

Show your human the image URLs. Every thumbnail also has an `editorUrl` that opens it in the web editor.

## Tools

| Tool | What it does | Needs key | Credits |
| --- | --- | --- | --- |
| `start_signup` | Email the human a sign-in code for their address. | no | - |
| `verify_signup` | Swap the code for an API key. Creates the account if needed. | no | - |
| `list_credit_packs` | Credit pack prices. | no | - |
| `buy_credits` | Stripe Checkout link for the human to pay. | yes | - |
| `get_account` | Email, plan and credit balance. | yes | - |
| `create_video_thumbnails` | Best results: a set of options designed from the YouTube video itself. | yes | 1 per variant |
| `get_video_thumbnails` | Poll a video job until it is COMPLETED. | yes | - |
| `generate_thumbnail` | One thumbnail from a prompt. | yes | 1 |
| `edit_thumbnail` | Change an existing thumbnail with an instruction. | yes | 1 |
| `analyze_video` | Thumbnail concepts and prompts for a video. | yes | - |
| `list_thumbnails` | Recent thumbnails on the account. | yes | - |
| `list_assets` | Saved faces, styles and brands with their ids. | yes | - |
| `generate_seo_titles` | Title ideas to pair with the thumbnail. | yes | - |

## REST API

Same flow over HTTPS with JSON bodies:

```bash
curl -X POST https://www.thumbnailcreator.com/api/v1/agents/signup -H 'Content-Type: application/json' \
  -d '{"email":"human@example.com","agentName":"My Agent"}'
curl -X POST https://www.thumbnailcreator.com/api/v1/agents/verify -H 'Content-Type: application/json' \
  -d '{"email":"human@example.com","code":"K7QM-4XPA"}'      # -> { data: { apiKey } }
curl https://www.thumbnailcreator.com/api/v1/billing/credit-packs
curl -X POST https://www.thumbnailcreator.com/api/v1/billing/checkout -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"packId":"pack_50"}'   # -> { data: { checkoutUrl } }
curl -X POST https://www.thumbnailcreator.com/api/v1/thumbnails/video-v2 -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{"youtubeUrl":"https://youtu.be/…","variantCount":4}'
curl https://www.thumbnailcreator.com/api/v1/thumbnails/video-v2/<jobId> -H "Authorization: Bearer $KEY"
```

Full API reference: https://www.thumbnailcreator.com/docs/api

## Rules

- Ask your human before buying credits or starting anything that spends more than a few credits.
- One account per human. Signing up with an email that already has an account connects to that account, not a new one.
- Your human can see and revoke agent keys under Settings → Organization → Developers.
- Support: support@thumbnailcreator.com
