Tellers Network Image Generation Tool (tlnw-generate-image)

tlnw-generate-image is a standalone, publishable package that unifies AI image generation for stories and posts in the Tellers Network ecosystem. It supports OpenAI (DALL-E 2, DALL-E 3, gpt-image-2, and legacy gpt-image-1.5) as well as Google Gemini Imagen 4 models.

Installation

pip install tlnw-generate-image

Features

• Extensible OOP Provider Architecture: Clean separation of model providers (DalleProvider, GptImageProvider, GoogleImagenProvider) with registry-based dynamic routing.
• Intelligent Size & Quality Preset Mapping: Standardizes orientation presets (landscape, portrait, square) and qualities, automatically converting them to provider-native formats: aspect ratios (e.g. "16:9") for Google Imagen, or concrete dimensions (e.g. "1792x1024") for OpenAI.
• Custom Dimension Resolution & Validation: Automatically maps exact resolution values (e.g., 1920x1080 or 1536x1024.txt in file names) to the closest supported native aspect ratios when routing to Imagen. For gpt-image-2, it validates custom resolution constraints locally (divisibility by 16, aspect ratios between 1:3 and 3:1, and a maximum resolution edge of 3840px with a minimum edge of 2160px).
• Auto-resolution of Output Sizing: Extracts target sizes from prompt filename trailing suffixes (e.g., -1536x1024.txt).
• Prompt Composition: Concatenates local directory illustration-master-prompt.txt automatically with individual scene prompts.
• Automatic WebP Conversion: Generates and optimizes WebP formats (featured.webp and thumbnail.webp with max-dimension constraints).
• Standardized Output Filenames: Output filenames are derived from the prompt file base: <prefix>-prompt.txt or <prefix>-prompt-<size>.txt become <prefix>.<ext>.
• Optional WEBP Copy: Use --webp to create an additional lossless <prefix>.webp copy alongside the main output.
• Thumbnail Generation: Use --thumbnail to create <prefix>-thumbnail.webp resized to max 768px with 75% quality.
• Dry Run: Use --dry-run to run the full pipeline locally without calling remote image generation APIs. This creates small placeholder PNGs and performs conversions so you can validate outputs without API keys.
• Recursive File Patterns: --file-pattern accepts glob patterns including ** for recursive discovery (e.g. --file-pattern "**/*-prompt-*.txt" root-folder).

Usage

Generate illustration for a story folder:

generate-image /path/to/story_folder --model dall-e-3 --webp --thumbnail

Process specific prompt files:

generate-image --file /path/to/prompt-1536x1024.txt --model imagen-4-ultra

Dry-run example (creates placeholders, no API calls):

generate-image /path/to/story_folder --dry-run --file-pattern "**/*-prompt-*.txt"