How to Generate YouTube Thumbnails with AI Using the Miraflow API

Create stunning, click-worthy YouTube thumbnails programmatically using the Miraflow YouTube Thumbnail Maker API. Whether you're building a content creation tool, automating your video workflow, or A/B testing thumbnail designs at scale, this API gives you full control over AI-powered thumbnail generation.

What You'll Learn

In this guide, you'll learn three powerful workflows:

1. Text-to-Thumbnail: Generate thumbnails from text descriptions alone

2. Reference Image: Use your own images as style/content references

3. YouTube Video Inspiration: Create new thumbnails based on existing YouTube videos

Each workflow is complete with curl examples and ready-to-use scripts.

Prerequisites

Before you begin, you'll need:

- A Miraflow account at miraflow.ai

- An API key (found in your account settings)

- Basic familiarity with REST APIs and command-line tools

API Overview

Authentication

All API requests require authentication using the `x-api-key` header:

bash
curl -H "x-api-key: YOUR_API_KEY" https://miraflow.ai/api/...

Workflow 1: Text-to-Thumbnail (Basic)

The simplest approach—just describe the thumbnail you want, and the AI generates it.

Generate a Thumbnail

bash
curl -X POST "https://miraflow.ai/api/thumbnail/generate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gaming Video Thumbnail",
    "prompt": "Epic gaming moment with dramatic lighting, a character in action pose, explosion effects in the background, bold red and orange colors, cinematic composition",
    "aspectRatio": "16:9"
  }'

Response:

json
{
  "result": "success",
  "jobId": "cm42ab3ou0008aggajj0jy5e2"
}

Poll for Completion

Thumbnail generation typically takes 15-45 seconds. Poll the status endpoint:

bash
curl -X GET "https://miraflow.ai/api/thumbnail/cm42ab3ou0008aggajj0jy5e2" \
  -H "x-api-key: YOUR_API_KEY"

Response (in progress):

json
{
  "result": "success",
  "status": "started",
  "progress": 45
}

Response (completed):

json
{
  "result": "success",
  "status": "completed",
  "id": "cm42ab3ou0008aggajj0jy5e2",
  "name": "Gaming Video Thumbnail",
  "prompt": "Epic gaming moment...",
  "imageUrl": "/api/media/cm42ab3ou0008aggajj0jy5e3/view",
  "downloadUrl": "/api/media/cm42ab3ou0008aggajj0jy5e3/view",
  "mediaId": "cm42ab3ou0008aggajj0jy5e3",
  "aspectRatio": "16:9",
  "createdAt": "2025-02-06T10:30:00.000Z"
}

Download Your Thumbnail

Access your thumbnail at:

https://miraflow.ai/api/media/cm42ab3ou0008aggajj0jy5e3/view

Workflow 2: With Reference Images

Use your own images to guide the AI's style, composition, or content. This is perfect for maintaining brand consistency or matching an existing visual style.

Step 1: Initialize Media Upload

First, prepare to upload your reference image:

bash
curl -X POST "https://miraflow.ai/api/media/initialize" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "reference.png",
    "contentType": "image/png",
    "fileSize": 1024000
  }'

Response:

json
{
  "mediaId": "cm42ab3ou0008aggajj0jy5e2",
  "uploadUrl": "https://s3.amazonaws.com/bucket/path?signature=..."
}

Step 2: Upload to S3

Upload your file directly to the presigned URL:

bash
curl -X PUT \
  -H "Content-Type: image/png" \
  --data-binary "@reference.png" \
  "UPLOAD_URL_FROM_PREVIOUS_STEP"

Step 3: Finalize Upload

Complete the upload process:

bash
curl -X POST "https://miraflow.ai/api/media/finalize" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "cm42ab3ou0008aggajj0jy5e2"
  }'

Step 4: Generate with Reference

Now generate a thumbnail using your reference image:

bash
curl -X POST "https://miraflow.ai/api/thumbnail/generate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Showcase Thumbnail",
    "prompt": "Create a vibrant YouTube thumbnail featuring this product. Add bold text saying AMAZING DEALS with an eye-catching background. Make it pop with high contrast colors.",
    "aspectRatio": "16:9",
    "referenceImageMediaIds": ["cm42ab3ou0008aggajj0jy5e2"]
  }'

Workflow 3: From YouTube Video URL

Create thumbnails inspired by existing YouTube videos. This workflow fetches the video's current thumbnail and uses it as a reference for generating a new, unique design.

How It Works

1. Extract the video ID from the YouTube URL

2. Fetch the existing thumbnail from YouTube's CDN

3. Upload it as a reference image

4. Generate a new thumbnail inspired by it

YouTube Thumbnail URLs

YouTube provides thumbnails at predictable URLs:

• https://img.youtube.com/vi/{VIDEO_ID}/maxresdefault.jpg (1280x720)
• https://img.youtube.com/vi/{VIDEO_ID}/hqdefault.jpg (480x360)
• https://img.youtube.com/vi/{VIDEO_ID}/mqdefault.jpg (320x180)

Extracting Video ID

From various YouTube URL formats:

API Reference

Generate Thumbnail Request Schema

json
{
  "name": "string (required)",
  "prompt": "string (required)",
  "aspectRatio": "16:9 | 9:16 (default: 16:9)",
  "referenceImageMediaIds": ["array of mediaIds (optional)"],
  "negativePrompt": "string (optional)",
  "seed": "integer (optional)"
}

List Thumbnails

bash
curl -X GET "https://miraflow.ai/api/thumbnails?page=1" \
  -H "x-api-key: YOUR_API_KEY"

Response:

json
{
  "result": "success",
  "thumbnails": [
    {
      "id": "cm42ab3ou0008aggajj0jy5e2",
      "name": "Gaming Thumbnail",
      "prompt": "Epic gaming moment...",
      "imageUrl": "/api/media/cm42ab3ou0008aggajj0jy5e3/view",
      "mediaId": "cm42ab3ou0008aggajj0jy5e3",
      "aspectRatio": "16:9",
      "createdAt": "2025-02-06T10:30:00.000Z"
    }
  ],
  "page": 1,
  "totalPages": 5,
  "totalCount": 100
}

Prompt Engineering Tips

Gaming Thumbnails

"Epic gaming moment with dramatic lighting, character in action pose,

explosion effects, neon accents, bold red and orange colors,

cinematic wide shot composition, game title space on left side"

Tutorial/Educational Thumbnails

"Clean professional tutorial thumbnail, person pointing at floating

code snippets, modern gradient background in blue and purple,

space for bold white title text, tech aesthetic, high contrast"

Vlog/Lifestyle Thumbnails

"Bright lifestyle vlog thumbnail, happy person with expressive face,

warm natural lighting, travel destination background,

vibrant saturated colors, text overlay space at top"

Product Review Thumbnails

"Professional tech review thumbnail, sleek product centered,

minimalist dark background with accent lighting,

rating stars graphic, modern clean aesthetic"

Using Negative Prompts

Exclude unwanted elements:

json
{
  "prompt": "Professional business thumbnail...",
  "negativePrompt": "blurry, low quality, distorted faces, text, watermark, grainy"
}

Best Practices

1. Aspect Ratios

- 16:9: Standard YouTube thumbnails (1280x720 recommended)

- 9:16: YouTube Shorts thumbnails

2. Polling Intervals

- Use 5-second intervals for thumbnail generation

- Most thumbnails complete in 15-45 seconds

- Implement exponential backoff for retries

3. Error Handling

Always check for failed status:

bash
if [ "$JOB_STATUS" = "failed" ]; then
  REASON=$(echo "$STATUS" | python3 -c "import sys, json; print(json.load(sys.stdin).get('reason', 'Unknown error'))")
  echo "Failed: $REASON"
  exit 1
fi

4. Using Seeds for Reproducibility

Generate consistent results with the same seed:

json
{
  "prompt": "Gaming thumbnail...",
  "seed": 12345
}

Brand Consistency

Use reference images from your brand kit to maintain consistent style across all thumbnails.

Next Steps

- Explore the full API documentation for all options

- Try the web interface to preview designs

Start creating click-worthy thumbnails at scale with the Miraflow API!