README

Video generation library for the xAI Grok Imagine API. This package provides an implementation of AdachSoft\VideoGenerationContracts\Contract\VideoGeneratorInterface for xAI, together with a small CLI helper for generating and downloading videos from the command line.

It is designed to be used together with the adachsoft/video-generation-contracts package, which defines the common DTOs, enums and interfaces.

Current stable version: 0.1.0.

Features

• xAI Grok Imagine video generation client using guzzlehttp/guzzle.
• Support for three input modes (as defined by the contracts layer):
  • text-to-video,
  • image-to-video,
  • video-to-video.
• Capability description via VideoGeneratorCapabilitiesDto:
  • format: MP4,
  • aspect ratio: landscape,
  • quality: standard,
  • minimum duration: 5 seconds,
  • maximum duration: 10 seconds,
  • at most 1 input media item,
  • supports status polling, does not use webhooks.
• Mapping of xAI job status responses to VideoJobDto and VideoStatusEnum.
• Provider-specific parameters DTO for xAI (XaiParametersDto).
• Convenience factory for building configured generators (XaiVideoGeneratorFactory).
• CLI tool (bin/cli) for quick testing and ad‑hoc video generation.

Requirements

• PHP ^8.1
• Composer
• Network access to https://api.x.ai
• A valid xAI API key with access to Grok Imagine video generation.

Runtime dependencies (installed automatically via Composer):

• adachsoft/video-generation-contracts ^0.1
• adachsoft/collection ^3.0
• guzzlehttp/guzzle ^7.10

For development (already listed in require-dev):

• phpunit/phpunit
• phpstan/phpstan
• rector/rector
• friendsofphp/php-cs-fixer
• vlucas/phpdotenv

Installation

Install the library via Composer:

composer require adachsoft/video-generation-xai

Composer will also install the required contracts package.

If you use this package inside another application, the CLI script will be available at:

vendor/adachsoft/video-generation-xai/bin/cli

You can call it with php from your project root.

Core classes

The library exposes the following main classes in the AdachSoft\VideoGenerationXai namespace:

• XaiVideoGenerator – implementation of VideoGeneratorInterface for xAI Grok Imagine.
• XaiCapabilitiesFactory – builds VideoGeneratorCapabilitiesDto describing what xAI supports.
• XaiJobMapper – maps raw xAI JSON responses into VideoJobDto and VideoResultDto.
• XaiParametersDto – provider‑specific parameters passed to xAI (model, resolution, optional image/video URLs).
• XaiVideoGeneratorFactory – convenience factory for building fully configured XaiVideoGenerator instances.

XaiVideoGenerator

XaiVideoGenerator:

• sends POST requests to https://api.x.ai/v1/videos/generations to start a job,
• sends GET requests to https://api.x.ai/v1/videos/{jobId} to poll job status,
• maps HTTP 400 errors to InvalidPromptException,
• maps HTTP 429 errors to RateLimitException,
• wraps other client errors in VideoGenerationException.

It currently does not implement remote job cancellation or listing jobs – cancel() always returns false, and listJobs() returns an empty VideoJobCollection.

Usage in PHP code

Below is a minimal example of how to wire the generator using Guzzle and the contracts package. The recommended way is to use the XaiVideoGeneratorFactory.

Creating the generator

<?php

use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\VideoAspectRatioEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoFormatEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoQualityEnum;
use AdachSoft\VideoGenerationXai\XaiVideoGeneratorFactory;
use GuzzleHttp\Client;

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

$apiKey = getenv('XAI_KEY');

$httpClient = new Client();
$factory = new XaiVideoGeneratorFactory();

$xaiVideoGenerator = $factory->create($httpClient, (string) $apiKey);

$request = new VideoRequestDto(
    format: VideoFormatEnum::Mp4,
    aspectRatio: VideoAspectRatioEnum::Landscape,
    quality: VideoQualityEnum::Standard,
    durationSeconds: 6,
    prompt: 'A short cinematic drone shot over a futuristic city at sunset',
);

$job = $xaiVideoGenerator->generate($request);

// Later – poll status
$status = $xaiVideoGenerator->getStatus($job->id);

if ($status->result !== null) {
    $videoUrl = $status->result->videoUrl;
    // Download or process the video URL as needed
}

Image‑to‑video example

<?php

use AdachSoft\VideoGenerationContracts\Collection\InputMediaCollection;
use AdachSoft\VideoGenerationContracts\Dto\InputMediaDto;
use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\InputMediaRoleEnum;
use AdachSoft\VideoGenerationContracts\Enum\InputMediaTypeEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoAspectRatioEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoFormatEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoQualityEnum;

$image = new InputMediaDto(
    url: 'https://example.com/reference-image.jpg',
    type: InputMediaTypeEnum::Image,
    role: InputMediaRoleEnum::Reference,
);

$request = new VideoRequestDto(
    format: VideoFormatEnum::Mp4,
    aspectRatio: VideoAspectRatioEnum::Landscape,
    quality: VideoQualityEnum::Standard,
    durationSeconds: 6,
    prompt: 'Turn this reference image into a short cinematic shot',
    inputMedia: new InputMediaCollection([$image]),
);

$job = $xaiVideoGenerator->generate($request);

For video‑to‑video requests, pass an InputMediaCollection with media of type InputMediaTypeEnum::Video.

Provider parameters (XaiParametersDto)

XaiParametersDto lets you pass some xAI‑specific options through the generic VideoRequestDto:

<?php

use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\VideoAspectRatioEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoFormatEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoQualityEnum;
use AdachSoft\VideoGenerationXai\XaiParametersDto;

$parameters = new XaiParametersDto(
    model: 'grok-imagine-video', // default model name
    resolution: '1080p',         // passed as `resolution` to the xAI API (check xAI docs for valid values)
);

$request = new VideoRequestDto(
    format: VideoFormatEnum::Mp4,
    aspectRatio: VideoAspectRatioEnum::Landscape,
    quality: VideoQualityEnum::Standard,
    durationSeconds: 6,
    prompt: 'A slow camera fly‑through of a neon city street at night',
    providerParameters: $parameters,
);

If you set imageUrl or videoUrl on XaiParametersDto, they are used as fallback sources when no input media objects are provided for image‑to‑video or video‑to‑video modes.

Capabilities

XaiCapabilitiesFactory returns a VideoGeneratorCapabilitiesDto that describes what this integration supports:

• Formats: VideoFormatEnum::Mp4 only.
• Aspect ratios: VideoAspectRatioEnum::Landscape.
• Qualities: VideoQualityEnum::Standard.
• Input media types: images and videos only.
• Input media roles: reference media.
• Duration range: between 5 and 10 seconds.
• Maximum input media items: 1.
• Supported modes:
  • text‑to‑video,
  • image‑to‑video,
  • video‑to‑video,
  • mixed mode is not supported.
• Status polling: supported.
• Webhooks: not supported.

If you pass a mixed‑mode request (e.g. multiple incompatible input types), XaiVideoGenerator will throw UnsupportedInputModeException.

CLI tool (bin/cli)

The repository contains a small CLI helper script in bin/cli that uses XaiVideoGenerator under the hood.

Environment variable

The CLI expects the xAI API key in the XAI_KEY environment variable. You can provide it either:

• via a .env file in the project root (loaded using vlucas/phpdotenv), or
• as a regular environment variable for the current process.

Example .env:

XAI_KEY=your_xai_api_key_here

Basic usage

From the project root of this package:

php bin/cli [--task TASK_ID] [--img IMAGE_URL_OR_PATH] [--text PROMPT] [--duration SECONDS] [prompt] [output-file.mp4]

When used as a dependency, call it from your application root:

php vendor/adachsoft/video-generation-xai/bin/cli [options]

Options

• --text PROMPT – prompt text; if omitted, the first positional argument is used as the prompt.
• --img IMAGE_URL_OR_PATH – optional reference image:
  • if a HTTP(S) URL, it is sent directly to xAI,
  • if a local file path, the script reads and base64‑encodes it as a data: URL.
• --duration SECONDS – optional duration in seconds (positive integer, default: 6).
• --task TASK_ID – if provided, the script does not create a new job; instead it only polls and prints the status of an existing xAI task.

Positional arguments:

• prompt – prompt text (used when --text is not given),
• output-file.mp4 – optional target file name; if omitted, a timestamped file name is generated.

Generated videos are always saved under the var/data directory relative to the project root. If the directory does not exist, it is created automatically.

Examples

Generate a text‑to‑video clip and save it to var/data/sunset.mp4:

php bin/cli --text "A cinematic drone shot over a futuristic city at sunset" sunset.mp4

Generate an image‑to‑video clip using a local JPEG file and a prompt:

php bin/cli --img ./examples/frame.jpg --text "Slow zoom out from the reference image" image_to_video.mp4

Check the status of an existing xAI job:

php bin/cli --task your_xai_task_id

The script prints the task ID, status, and when available the resulting video URL. When the job finishes successfully, it downloads the video and stores it in var/data.

Versioning and changelog

This project follows a simple semantic versioning scheme. The first public release is 0.1.0, which contains the initial xAI Grok Imagine video generator implementation, capabilities factory, job mapper, provider parameters DTO, CLI tool and convenience factory.

See CHANGELOG.md for a detailed list of changes between versions.

Error handling

XaiVideoGenerator can throw the following exceptions from the contracts package:

• InvalidPromptException – when xAI returns HTTP 400 (invalid or moderated prompt).
• RateLimitException – when xAI returns HTTP 429 (too many requests).
• VideoGenerationException – for other HTTP or mapping errors.
• UnsupportedInputModeException – when the provided input mode is not supported by xAI.

Make sure you catch these exceptions in your application code to implement proper retry or fallback strategies.

License

This library is released under the MIT License.