Documentation menu

Text to Image

Generate images from a text prompt in PHP with local Stable Diffusion models such as stabilityai/sd-turbo. CLI and PHP examples, options and errors.

Generate an image from a text prompt with a Diffusers text-to-image model, such as stabilityai/sd-turbo, running on your own hardware.

Setup#

Terminal 
vendor/bin/loves-ai setup text-to-image
vendor/bin/loves-ai pull stabilityai/sd-turbo

Supported models#

Use a complete Diffusers pipeline: its repository has a model_index.json. Add-ons like embeddings or LoRAs, and single-file checkpoints, cannot be used on their own, so the runner rejects them with an explanation before starting.

  • stabilityai/sd-turbo: fast, good results in a single step with guidance 0
  • SfinOe/stable-diffusion-v1.5: the classic Stable Diffusion 1.5 pipeline

From the command line#

Terminal 
vendor/bin/loves-ai text-to-image stabilityai/sd-turbo "a cozy cat by the fireplace" --steps=1 --guidance=0
Output 
🎨 Painting your image with stabilityai/sd-turbo… Masterpieces take a moment — perfect time for a hot chocolate and a cookie 🍪
If you wish to see all logs, re-run the command with the "--debug" option.
🎉 Image saved to /Users/you/tmp/hugging-face/images/20260915-142501-a3f09c.png

Options#

Option Meaning
--output=PATH Image file to write (default: a timestamped .png in output_dir)
--negative-prompt=TEXT What the image should not contain
--steps=N Inference steps (default: the model's own)
--guidance=SCALE Guidance scale; turbo models use 0 (default: the model's own)
--width=PX, --height=PX Image size (default: the model's native size)
--seed=N Random seed, for reproducible images
--device=DEVICE cpu, cuda, mps… (default: the best available)
--log-file=PATH Append the runner's output to this file
--debug Show the runner's output while generating

Values are passed to the model as they are, so one it cannot handle (a prompt that is too long, an unsupported size…) makes the run fail. Defaults come from config/text-to-image.php (output_dir, log_file).

From PHP#

PHP 
use PhpLovesAi\Runner\TextToImage;

// Finds the runner and the pulled model in the project's .local directory by itself.
$image = (new TextToImage())->generate(
    model: 'stabilityai/sd-turbo',
    prompt: 'a cozy cat by the fireplace',
    outputPath: storage_path('app/cat.png'),
    steps: 1,
    guidanceScale: 0.0,
);
// '/var/www/my-app/storage/app/cat.png'

In a Laravel queue job#

Image generation takes seconds to minutes, so run it in a queued job instead of a web request:

app/Jobs/GenerateImageJob.php 
namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use PhpLovesAi\Runner\TextToImage;

class GenerateImageJob implements ShouldQueue
{
    use Queueable;

    public function __construct(public string $prompt) {}

    public function handle(TextToImage $textToImage): void
    {
        $textToImage->generate(
            model: 'stabilityai/sd-turbo',
            prompt: $this->prompt,
            outputPath: storage_path('app/images/'.uniqid().'.png'),
            steps: 1,
            guidanceScale: 0.0,
        );
    }
}

Errors#

  • BinaryNotInstalledException when setup text-to-image has not been run
  • ModelNotFoundException when the model was not pulled yet
  • UnsupportedModelException when the pulled model is not a complete Diffusers text-to-image model
  • RunFailedException, with the runner's error output, when generation fails