README

A PHP 8.3+ adapter for generating videos with the Sogni Creative Agent API. It implements the VideoGeneratorInterface from adachsoft/video-generation-contracts and supports text-to-video and image-to-video workflows.

Features

Create Sogni video-generation workflows and retrieve their status, cancel them, or list jobs.
Generate videos from a text prompt or reference images.
Use local image files directly: the adapter reads their bytes and uploads them through Sogni's signed upload flow. It does not create a temporary image file. HTTP(S) image URLs are passed to Sogni as references and must be accessible to the provider.
Use the included CLI to submit a generation request, wait for completion, and save the resulting video under var/videos/.
Optionally log outgoing JSON request payloads to standard error.

Requirements

PHP 8.3 or newer
Composer
A Sogni API key

Installation

composer require adachsoft/video-generation-sogni

Configuration

The CLI reads the project-root .env file. Copy .env.example to .env and set your credentials:

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

SOGNI_BASE_URI is optional and defaults to https://api.sogni.ai. Existing process environment variables take precedence over values in .env. Do not commit your .env file or expose your API key.

When using the PHP library directly, load your application's environment configuration yourself and pass the API key to the factory. The factory does not load .env files.

Command-line usage

Run the CLI from the package root:

php bin/gen_vid.php "A cinematic sunrise over a quiet ocean"

Use --input-image once per reference image. Values can be local file paths or HTTP(S) URLs:

php bin/gen_vid.php "Bring this scene to life" \
  --input-image=./images/first-frame.png \
  --input-image=./images/style-reference.png \
  --model=ltx25 \
  --duration=5

Local files are uploaded directly to Sogni using its signed upload URL flow; they do not need to be hosted at an HTTP URL first. HTTP(S) references are passed through to Sogni. The provider advertises support for up to eight input images and video durations from 5 to 10 seconds.

CLI options

Option	Description
`<prompt>`	Required video prompt. Quote it when it contains spaces.
`--input-image=<path-or-url>`	Optional image input. Repeat the option to provide multiple images.
`--model=<model>`	Optional Sogni model. Defaults to `ltx25`.
`--duration=<seconds>`	Optional positive integer duration. Defaults to 5 seconds; Sogni currently supports 5–10 seconds.
`--log=0\\|1`	Optional outgoing request-payload logging. Defaults to `0` (disabled). With `--log=1`, request method, URI, and JSON body are written to standard error; authorization headers are not logged. Payloads may contain prompts or image URLs.
`--help`	Display command usage.

The CLI prints the effective prompt and options at startup. When generation finishes, it downloads the video to var/videos/ using the job identifier as the filename.

For example, to enable payload logging:

php bin/gen_vid.php "A mountain lake at sunrise" --log=1

Using the PHP library

Create a generator and submit a text-to-video request:

<?php

declare(strict_types=1);

use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\VideoAspectRatioEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoFormatEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoQualityEnum;
use AdachSoft\VideoGenerationSogni\Factory\SogniVideoGeneratorFactory;

require __DIR__ . '/vendor/autoload.php';

$apiKey = getenv('SOGNI_API_KEY');
if (!is_string($apiKey) || trim($apiKey) === '') {
    throw new RuntimeException('Set the SOGNI_API_KEY environment variable.');
}

$generator = SogniVideoGeneratorFactory::create(trim($apiKey));
$request = new VideoRequestDto(
    format: VideoFormatEnum::Mp4,
    aspectRatio: VideoAspectRatioEnum::Landscape,
    quality: VideoQualityEnum::Standard,
    durationSeconds: 5,
    prompt: 'A cinematic sunrise over a quiet ocean',
);

$job = $generator->generate($request);
echo "Submitted job: {$job->id}" . PHP_EOL;

For image-to-video generation, add images to the request's InputMediaCollection. Local paths are uploaded by the provider; URLs are passed through:

<?php

declare(strict_types=1);

use AdachSoft\VideoGenerationContracts\Collection\InputMediaCollection;
use AdachSoft\VideoGenerationContracts\Dto\InputMediaDto;
use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\InputMediaTypeEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoAspectRatioEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoFormatEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoQualityEnum;
use AdachSoft\VideoGenerationSogni\Factory\SogniVideoGeneratorFactory;

require __DIR__ . '/vendor/autoload.php';

$apiKey = getenv('SOGNI_API_KEY');
if (!is_string($apiKey) || trim($apiKey) === '') {
    throw new RuntimeException('Set the SOGNI_API_KEY environment variable.');
}

$generator = SogniVideoGeneratorFactory::create(trim($apiKey));
$inputMedia = new InputMediaCollection();
$inputMedia->add(new InputMediaDto(
    url: __DIR__ . '/reference.png',
    type: InputMediaTypeEnum::Image,
));
$inputMedia->add(new InputMediaDto(
    url: 'https://example.com/another-reference.png',
    type: InputMediaTypeEnum::Image,
));

$request = new VideoRequestDto(
    format: VideoFormatEnum::Mp4,
    aspectRatio: VideoAspectRatioEnum::Landscape,
    quality: VideoQualityEnum::Standard,
    durationSeconds: 5,
    prompt: 'Animate the scene with gentle camera movement',
    inputMedia: $inputMedia,
);

$job = $generator->generate($request);
echo "Submitted job: {$job->id}" . PHP_EOL;

generate() returns a job DTO. Use getStatus($jobId) to poll the workflow, cancel($jobId) to request cancellation, listJobs() to retrieve jobs, and getCapabilities() to inspect provider capabilities. When a job is complete, its result contains the generated video's URL. The CLI also downloads that artifact locally.

Provider capabilities

The provider supports MP4 output, text-to-video and image-to-video generation, standard and high quality, landscape, portrait, square, and cinema aspect ratios, and 5–10 second videos. It advertises up to eight input images. Video-to-video and mixed media input are not supported.

The CLI's default model is ltx25. The wan3-uncensored CLI model alias is mapped to Sogni's wan3.0-spicy-video model identifier.

Tests

Run the default PHPUnit suite:

vendor/bin/phpunit

The production API test is excluded from the default suite. It requires SOGNI_API_KEY and creates, inspects, and cancels a real Sogni workflow:

vendor/bin/phpunit --group production

The PHPUnit bootstrap loads the project-root .env file when present.

License

This package is licensed under the MIT License.

adachsoft / video-generation-sogni

Package info

Security

Statistics