README

This package provides shared PHP interfaces, DTOs, enums and collections that define a common contract for video generation providers.

It is designed to be used by both video generation clients and concrete provider implementations so they can communicate using a stable, provider-agnostic API.

Requirements

• PHP 8.3 or higher
• adachsoft/collection ^3.0

Installation

Install via Composer:

composer require adachsoft/video-generation-contracts

Provided building blocks

Contracts

• AdachSoft\VideoGenerationContracts\Contract\VideoGeneratorInterface
  Main entry point for video generation providers (submitting requests, fetching jobs, listing jobs, discovering capabilities).
• AdachSoft\VideoGenerationContracts\Contract\VideoWebhookHandlerInterface
  Contract for handling asynchronous webhook callbacks with job status updates.

DTOs

• VideoRequestDto – describes a video generation request (format, aspect ratio, quality, duration, prompt, input media).
• VideoResultDto – describes the final generated video (download URL, size, duration, metadata).
• VideoJobDto – represents a long-running generation job with status and timestamps.
• VideoMetadataDto – additional metadata about the result.
• InputMediaDto – represents a single media input (image or video) with an optional role.
• ProviderParametersDto – optional provider-specific configuration.
• VideoGeneratorCapabilitiesDto – describes what a concrete provider supports.

Enums

• VideoFormatEnum – output format (e.g. MP4, WebM, GIF).
• VideoAspectRatioEnum – aspect ratio (landscape, portrait, square, etc.).
• VideoQualityEnum – quality presets (draft, standard, high).
• VideoStatusEnum – job status (pending, processing, done, failed, cancelled).
• InputMediaTypeEnum – input media type (image, video).
• InputMediaRoleEnum – logical role of a media input (content, style, reference).

Collections

Immutable and mutable collections built on top of adachsoft/collection for:

• VideoJobCollection
• VideoFormatCollection
• VideoAspectRatioCollection
• VideoQualityCollection
• InputMediaCollection
• InputMediaTypeCollection
• InputMediaRoleCollection

These collections provide type-safe storage and convenience helpers such as filtering by status, role or type.

Exceptions

Domain-specific exceptions that providers and clients can share:

• InvalidPromptException
• UnsupportedFormatException
• UnsupportedInputModeException
• RateLimitException
• GenerationFailedException
• VideoGenerationException (base class)

Basic usage

Implementing a provider

To integrate a concrete video generation provider, implement VideoGeneratorInterface in your library or application:

<?php

declare(strict_types=1);

use AdachSoft\VideoGenerationContracts\Contract\VideoGeneratorInterface;
use AdachSoft\VideoGenerationContracts\Dto\VideoJobDto;
use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\VideoStatusEnum;
use AdachSoft\VideoGenerationContracts\Collection\VideoJobCollection;

final class AcmeVideoGenerator implements VideoGeneratorInterface
{
    public function generate(VideoRequestDto $videoRequestDto): VideoJobDto
    {
        // submit request to provider API and return initial job
    }

    public function getJob(string $id): VideoJobDto
    {
        // fetch job status from provider
    }

    public function listJobs(?VideoStatusEnum $videoStatusEnum = null): VideoJobCollection
    {
        // list jobs, optionally filtered by status
    }

    public function getProviderName(): string
    {
        return 'acme-video';
    }
}

Consuming a provider

Client code can depend purely on the contracts without coupling to a specific implementation:

<?php

declare(strict_types=1);

use AdachSoft\VideoGenerationContracts\Contract\VideoGeneratorInterface;
use AdachSoft\VideoGenerationContracts\Dto\InputMediaDto;
use AdachSoft\VideoGenerationContracts\Dto\InputMediaCollection;
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;

final class GenerateIntroVideoHandler
{
    public function __construct(
        private readonly VideoGeneratorInterface $videoGenerator,
    ) {
    }

    public function __invoke(string $prompt, string $imageUrl): void
    {
        $media = new InputMediaCollection([
            new InputMediaDto($imageUrl, InputMediaTypeEnum::Image),
        ]);

        $request = new VideoRequestDto(
            VideoFormatEnum::Mp4,
            VideoAspectRatioEnum::Landscape,
            VideoQualityEnum::Standard,
            15,
            $prompt,
            $media,
        );

        $job = $this->videoGenerator->generate($request);

        // persist job id, trigger polling or wait for webhooks
    }
}

Versioning and license

This library is versioned via Git tags only.
License: MIT.