artryazanov / yt-cover-gen

v3.1.1 2026-11-04 10:34 UTC

Requires

• php: ^8.2
• ext-gd: *
• ext-json: *
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.0 || ^2.0
• psr/log: ^1.0 || ^2.0 || ^3.0

Requires (Dev)

• larastan/larastan: ^3.9
• laravel/pint: ^1.27
• orchestra/testbench: ^9.0 || ^10.0
• pestphp/pest: ^2.0 || ^3.0

Suggests

• guzzlehttp/guzzle: PSR-18 HTTP client implementation
• guzzlehttp/psr7: PSR-17 HTTP factory implementation
• illuminate/support: Required for optional Laravel ServiceProvider integration

MIT

• Artem Ryazanov

Published on Packagist.org on 2026-11-04 10:54 UTC

README

Introduction

YouTube AI Cover Generator (artryazanov/yt-cover-gen) is a framework-agnostic PHP package designed to automatically generate viral, high-CTR (Click-Through Rate) YouTube thumbnails from gameplay screenshots using Google Gemini multimodal AI models.

It leverages powerful AI vision and image editing capabilities to analyze a screenshot, understand the context, and generate a stylized, professional-looking thumbnail with compelling text overlays and branding, strictly adhering to the game's art style.

Examples

Source	Result	Model
		Gemini gemini-3-pro-image

Features

• Framework Agnostic: Can be used standalone in any PHP 8.2+ project via standard PSR interfaces.
• Laravel Integration: Includes an optional Service Provider and configuration publishing.
• Configurable Models: Supports gemini-nano-banana-2.1 (default), gemini-3.1-flash-image, gemini-3-pro-image for image generation, and gemini-4-argon (default) or gemini-3.1-pro-preview for text generation and validation.
• Smart Text Generation: If the input title is already compact (<= 5 words and <= 30 characters, ignoring standalone separator tokens like - or |), it is used directly to save API tokens and time. If it is longer, a text LLM condenses it into a short, punchy 2–5 word (up to 30 characters) clickbait headline while strictly preserving concrete specifics (chapters, missions, locations, characters, or bosses) and stripping SEO boilerplate.
• Smart Logo Extraction: Optionally pass an official game cover to accurately reproduce the game's logo in the thumbnail. The generator uses AI to isolate a clean logo from the cover and caches it by MD5 hash to prevent unwanted cover art elements from bleeding into the final thumbnail.
• Self-Correcting Validation Loop: Automatically evaluates the generated thumbnail using a vision-language model to check for AI artifacts, spelling errors, and readability. If the thumbnail fails validation, it cleans up the rejected file and regenerates up to 3 times with specific correction instructions.
• Smart Image Processing: Automatically center-crops images to the target aspect ratio (e.g. 16:9, 9:16, 1:1) without geometric distortion, converts formats, detects real binary MIME types, and handles Base64 encoding/decoding using GD (no external binaries required).
• PSR-3 Logging Support: Optionally accepts a Psr\Log\LoggerInterface to log validation retries and auxiliary API warnings.
• Prompt Engineering: Built-in, battle-tested prompt templates optimized for high CTR (including automatic 360° Video badge detection).

Requirements

• PHP 8.2 or higher (tested up to PHP 8.5)
• ext-gd extension
• ext-json extension
• PSR-17 and PSR-18 compatible HTTP client/factory (e.g. guzzlehttp/guzzle and guzzlehttp/psr7)

Installation

Install the package via Composer:

composer require artryazanov/yt-cover-gen

Configuration

Laravel

1. Publish the configuration file:

   php artisan vendor:publish --tag=yt-cover-gen-config

2. Configure environment variables (.env):

   # Gemini Configuration
   GEMINI_API_KEY=AIza...
   YT_COVER_GEN_GEMINI_MODEL=gemini-nano-banana-2.1
   YT_COVER_GEN_GEMINI_TEXT_MODEL=gemini-4-argon
   YT_COVER_GEN_GEMINI_ASPECT_RATIO=16:9
   YT_COVER_GEN_GEMINI_RESOLUTION=1K

Generic PHP

For non-Laravel projects, you can use CoverGeneratorFactory to instantiate the generator directly without any framework dependencies.

Usage

Basic Usage (Laravel)

Inject CoverGeneratorInterface (or GeminiCoverGenerator) into your class (Controller, Command, Job, etc.):

use Artryazanov\YtCoverGen\Contracts\CoverGeneratorInterface;

class CreateThumbnail
{
    public function __construct(
        private CoverGeneratorInterface $generator
    ) {}

    public function handle(): void
    {
        $pathToScreenshot = '/path/to/screenshot.jpg';
        $gameName = 'Elden Ring';
        $videoTitle = 'NO HIT RUN PART 1';
        $gameCover = '/path/to/official_cover.png'; // Optional: for accurate logo generation

        // Returns absolute path to the generated image
        $coverPath = $this->generator->generate(
            $pathToScreenshot, 
            $gameName, 
            $videoTitle,
            $gameCover
        );
        
        echo "Thumbnail generated at: $coverPath";
    }
}

Advanced Usage (Standalone PHP / Custom Configuration)

You can use CoverGeneratorFactory::createGemini() with either enum instances or plain strings:

use Artryazanov\YtCoverGen\CoverGeneratorFactory;
use Artryazanov\YtCoverGen\Enums\GeminiAspectRatioEnum;
use Artryazanov\YtCoverGen\Enums\GeminiImageModelEnum;
use Artryazanov\YtCoverGen\Enums\GeminiResolutionEnum;
use Artryazanov\YtCoverGen\Enums\GeminiTextModelEnum;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$client = new Client();
$httpFactory = new HttpFactory();

$generator = CoverGeneratorFactory::createGemini(
    'your-gemini-api-key',
    $client,                                      // PSR-18 ClientInterface
    $httpFactory,                                 // PSR-17 RequestFactoryInterface
    $httpFactory,                                 // PSR-17 StreamFactoryInterface
    '/path/to/output/dir',                        // Optional output directory (defaults to sys_get_temp_dir())
    GeminiImageModelEnum::GEMINI_NANO_BANANA_2_1, // Optional image model (Enum or string)
    GeminiTextModelEnum::GEMINI_4_ARGON,          // Optional text/validation model (Enum or string)
    GeminiAspectRatioEnum::RATIO_16_9,            // Optional aspect ratio (Enum or string)
    GeminiResolutionEnum::RES_1K,                 // Optional resolution (Enum or string)
    $logger                                       // Optional PSR-3 LoggerInterface
);

$path = $generator->generate('screenshot.jpg', 'My Game', 'Awesome Video', 'cover.jpg');

Supported Enums & Options

Image Models (Artryazanov\YtCoverGen\Enums\GeminiImageModelEnum)

• gemini-nano-banana-2.1 (Default)
• gemini-3.1-flash-image
• gemini-3-pro-image

Text & Validation Models (Artryazanov\YtCoverGen\Enums\GeminiTextModelEnum)

• gemini-4-argon (Default)
• gemini-3.1-pro-preview

Aspect Ratios (Artryazanov\YtCoverGen\Enums\GeminiAspectRatioEnum)

• 16:9 (Default), 9:16, 1:1, 4:3, 3:4, 21:9, 3:2, 2:3, 5:4, 4:5, 4:1, 1:4, 8:1, 1:8

Resolutions (Artryazanov\YtCoverGen\Enums\GeminiResolutionEnum)

• 1K (Default), 512, 2K, 4K

Testing & Quality Checks

# Run test suite
composer test

# Run test suite with code coverage
composer test-coverage

# Run PHPStan static analysis (Level 9)
composer analyse

# Check code style (Laravel Pint)
composer lint

License

The MIT License (MIT). Please see License File for more information.