README

A PHP 8.2+ client and CLI for generating images through the Sogni API.

Requirements

PHP 8.2 or newer
Composer
A Sogni API key

Installation

composer install
cp .env.example .env

Set the API key in .env:

SOGNI_API_KEY=your-api-key
SOGNI_BASE_URI=https://api.sogni.ai

Generate an image

Use a prompt directly from the command line:

php bin/generate_image.php "A cinematic portrait in a dark fantasy style"

The image is downloaded to var/img/.

The CLI prints the selected model, generation options and the workflow ID before polling for results. safe_content_filter is disabled by the CLI.

Prompt file

php bin/generate_image.php --prompt=var/prompts/portrait.txt

Generate multiple images

php bin/generate_image.php --count=3 "A red fox in fresh snow"

Each image receives a separate random seed when --seed is not provided.

Input images

Input images are optional. Use repeated --input-image arguments to provide local files, remote HTTPS URLs, or a combination of both. Without this option, the CLI keeps its existing prompt-only behavior.

Use a local image with a prompt:

php bin/generate_image.php \
  --input-image=var/img/reference.png \
  "Transform this reference into a cinematic sci-fi scene"

Use a remote image with a prompt:

php bin/generate_image.php \
  --input-image="https://example.com/reference.png" \
  "Create a realistic editorial portrait based on this image"

Pass multiple local and remote images in one request:

php bin/generate_image.php \
  --input-image=var/img/character.png \
  --input-image="https://example.com/background.png" \
  "Combine the character and background into one realistic image"

Local files are uploaded through the Sogni image upload flow before generation. Remote URLs are passed directly as image references. Input images can also be configured in JSON:

{
    "input_images": [
        "var/img/character.png",
        {
            "source": "https://example.com/background.png",
            "type": "reference",
            "weight": 0.75
        }
    ]
}

When --input-image is provided, it takes precedence over input_images from the JSON configuration. Supported configured image types are reference, style, and mask.

For more examples, see image generation examples.

For reproducible variations, provide a seed:

php bin/generate_image.php --seed=123456789 --count=3 "A red fox in fresh snow"

The resulting seeds are 123456789, 123456790 and 123456791.

JSON configuration

Create a configuration file such as var/config/generation.json:

{
    "model_id": "chroma-detail",
    "count": 2,
    "steps": 25,
    "cfg_scale": 6.0,
    "sampler_name": "DPM++ 2M Karras",
    "samples": 1,
    "width": 512,
    "height": 768,
    "negative_prompt": "blurry, low quality, watermark, text"
}

Run it with a prompt from a file:

php bin/generate_image.php \
  --config=var/config/generation.json \
  --prompt=var/prompts/portrait.txt

The configuration may use either model or model_id. If both are present, model takes precedence. CLI options override values from the JSON file.

Additional JSON fields are passed to the selected model as workflow arguments. Model parameters are not universal; use only parameters supported by the selected model.

The following example is equivalent to the command above and places the prompt in the JSON file:

{
    "model": "chroma-detail",
    "prompt": "A cinematic portrait in a dark fantasy style",
    "count": 1,
    "steps": 25,
    "cfg_scale": 6.0,
    "negative_prompt": "blurry, low quality"
}

php bin/generate_image.php --config=var/config/generation.json

See CLI usage for the complete command reference.

List available models

List all image models:

php bin/list_models.php --media-type=image

List text-to-image models marked as mature or uncensored:

php bin/list_models.php \
  --media-type=image \
  --text-to-image \
  --nsfw

Search model metadata:

php bin/list_models.php \
  --media-type=image \
  --text-to-image \
  --filter=uncensored

Tests

Run the complete test suite:

vendor/bin/phpunit

Run the production API tests explicitly:

vendor/bin/phpunit --group production

Production tests require SOGNI_API_KEY in .env and consume API credits.

adachsoft / ai-image-sogni

Package info

Security

Statistics