ThumbAPI + GitHub Actions: Auto-Generate Thumbnails in CI/CD

Wire ThumbAPI into your GitHub Actions workflows and let your pipeline produce cover images, release cards, and social graphics automatically — on every push, release, or schedule. No design step, no manual export, no missing assets.

What You Can Do With ThumbAPI + GitHub Actions

GitHub Actions runs arbitrary commands on any repository event. Adding a single curl step that calls the ThumbAPI generate endpoint unlocks automated thumbnail creation for any developer-driven workflow:

• Generate blog cover images when a new Markdown post is pushed
• Attach a release card to every published GitHub release
• Schedule weekly LinkedIn or X images from your CHANGELOG
• Open a follow-up PR that commits the generated image to your repo
• Trigger thumbnail generation manually via workflow_dispatch

Step-by-Step Setup

Step 1: Get Your ThumbAPI Key

Sign up at app.thumbapi.dev and copy your API key. The free tier gives you 50 credits per month — enough to test a workflow end-to-end before you commit to a paid plan.

Step 2: Store the Key as a Repository Secret

Never hard-code your API key in a workflow file. Store it as an encrypted repository secret instead.

1. Open your GitHub repository
2. Go to Settings → Secrets and variables → Actions
3. Click "New repository secret"
4. Name: THUMB_API_KEY
5. Value: paste your API key from app.thumbapi.dev
6. Click "Add secret"

Step 3: Add a Workflow File

Create a YAML file under .github/workflows/. The example below triggers on a push to any Markdown file in posts/ and uploads the generated thumbnail as a workflow artifact.

name: Generate Thumbnail
on:
  push:
    paths:
      - 'posts/**.md'

jobs:
  thumbnail:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate cover image
        env:
          THUMB_API_KEY: ${{ secrets.THUMB_API_KEY }}
        run: |
          curl -X POST https://api.thumbapi.dev/v1/generate \
            -H "x-api-key: $THUMB_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"title":"My Latest Post","format":"blogpost"}' \
            -o thumbnail.webp

      - uses: actions/upload-artifact@v4
        with:
          name: thumbnail
          path: thumbnail.webp

The format field accepts youtube, instagram, x, linkedin, or blogpost. Use usePhoto: true for a saved headshot or useLogo: true for a branded variant.

Example Workflows

Workflow 1: Attach a Card to Every GitHub Release

Trigger on the release event, pull the release name into a ThumbAPI call, and upload the result as a release asset. Useful for changelog blogs, social sharing, and downloadable announcement cards.

name: Generate Release Thumbnail
on:
  release:
    types: [published]

jobs:
  thumbnail:
    runs-on: ubuntu-latest
    steps:
      - name: Generate YouTube-style release card
        env:
          THUMB_API_KEY: ${{ secrets.THUMB_API_KEY }}
          RELEASE_TITLE: ${{ github.event.release.name }}
        run: |
          curl -X POST https://api.thumbapi.dev/v1/generate \
            -H "x-api-key: $THUMB_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"title\":\"$RELEASE_TITLE\",\"format\":\"youtube\",\"useLogo\":true}" \
            -o release-card.webp

      - name: Upload to release assets
        uses: softprops/action-gh-release@v2
        with:
          files: release-card.webp

Workflow 2: Weekly Social Card From CHANGELOG

Run on a cron schedule, read the latest entry from your CHANGELOG.md, and generate a LinkedIn-formatted image for the marketing team to pick up. Pair it with workflow_dispatch so you can fire it manually too.

name: Weekly Social Card
on:
  schedule:
    - cron: '0 9 * * MON'   # every Monday 09:00 UTC
  workflow_dispatch:

jobs:
  social:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Read latest changelog entry
        id: changelog
        run: |
          TITLE=$(head -n 1 CHANGELOG.md | sed 's/# //')
          echo "title=$TITLE" >> $GITHUB_OUTPUT

      - name: Generate LinkedIn card
        env:
          THUMB_API_KEY: ${{ secrets.THUMB_API_KEY }}
        run: |
          curl -X POST https://api.thumbapi.dev/v1/generate \
            -H "x-api-key: $THUMB_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"title\":\"${{ steps.changelog.outputs.title }}\",\"format\":\"linkedin\"}" \
            -o linkedin-card.webp

Production Tips

• Commit the image back into the repo. Use git-auto-commit-action or a follow-up PR step so the generated thumbnail lives next to your post.
• Cache the binary. Pin actions/checkout@v4 and actions/upload-artifact@v4 to specific versions so a new major release never breaks your pipeline.
• Fail loudly on a non-2xx response. Add --fail-with-body to your curl so the job exits non-zero if ThumbAPI returns an error.
• Use --data @body.json for complex payloads. Inline JSON gets messy with quoting; piping a file is cleaner once you have multiple flags.

Common Questions

Does ThumbAPI have a published GitHub Action?

Not yet — you call the REST endpoint directly with curl. That keeps the workflow transparent and lets you adjust headers, timeouts, and error handling without waiting on a wrapper action.

How long does generation take?

Most thumbnails return in 3–8 seconds. That fits well inside a single GitHub Actions step — no chunking or background polling needed.

What happens if I exceed my plan in CI?

You'll get an HTTP 429 with a clear error body. The workflow step will fail (assuming --failis set), so failed generations don't silently produce missing assets. Credits reset at the start of each billing period.