Prisma Laravel Package

Getting Started

0.7.0 is a major capability expansion: video generation is no longer a niche path, with providers for xAI, Veo, Runway, MiniMax, Luma, Gemini Omni, BytePlus, Bedrock, Alibaba, and OpenRouter, plus video description/repaint/extend/upscale/uncrop support on selected providers. OpenRouter now also covers image and audio, and Ideogram moves to V4 with transparent image generation/editing and async support.

Minimal steps:

1. Install/upgrade with Composer and pin the version while validating the breaking async change:

   composer require aimeos/prisma:^0.7
   

2. Read the README and inspect src/Provider/* plus the tests for the providers you plan to use. The release notes are useful, but provider capability differences matter more than the headline list.
3. Configure credentials through the package’s documented config/env mechanism. If the package exposes a publishable config, publish it and cache only after all provider credentials are set:

   php artisan config:cache
   

4. Start with one provider and one operation before wiring multiple modalities. For a Laravel app, the fastest first use case is usually:
   • generate an image with Ideogram V4 for transparent product/asset imagery, or
   • generate a short video through OpenRouter/Runway and store the returned FileResponse with Laravel’s filesystem.

First-use checklist:

• Use a queued job for video operations.
• Store returned files in storage/app/... or an S3 disk, not in the database.
• Persist provider request IDs / async handles so polling can resume after a worker restart.
• Verify the installed provider actually supports the operation you need; 0.7.0 adds many providers, but not every provider supports every video operation.

Implementation Patterns

Wrap Prisma in an application service. Keep provider names, model IDs, timeouts, and storage rules out of controllers. A small service layer makes it easy to switch providers and to apply Laravel-specific concerns like logging, retries, and authorization.

Illustrative shape:

final class AiMediaService
{
    public function generateVideo(string $prompt, array $options = []): FileResponse
    {
        // Adapt to the package's actual client/factory API.
        return Prisma::video()
            ->provider(config('prisma.video_provider'))
            ->generate($prompt, $options);
    }
}

Use queues for video generation. Video jobs are slow and expensive. Submit the request from a queued job, store the async handle/response ID, and poll in a second job or scheduled command. Avoid holding an HTTP request open while a provider renders video.

final class GenerateVideoJob implements ShouldQueue
{
    public function __construct(public int $assetId, public string $prompt) {}

    public function handle(AiMediaService $ai): void
    {
        $response = $ai->generateVideo($this->prompt);

        // Persist file/URL and update asset status.
    }
}

Treat async as a first-class workflow. The fromAsync() change in 0.7.0 affects FileResponse and TextResponse. In production, pass a timeout in seconds where you resolve async results, or omit the argument only when you intentionally want unlimited polling. Store the async handle and a deadline so retries and redeploys do not create orphaned jobs.

Maintain a provider capability map. The 0.7.0 release adds operations selectively. A useful starting map from the release notes:

• Video generation: xAI, Veo, Runway, MiniMax, Luma, Gemini Omni, BytePlus, Bedrock, Alibaba, OpenRouter.
• Video description: BytePlus, Bedrock, Alibaba.
• Video repaint: Gemini Omni, Runway, BytePlus, xAI, Luma, Alibaba, plus reference-guided repaint support.
• Video extension: Alibaba, BytePlus, xAI.
• Video upscaling: Runway.
• Video uncrop: Alibaba, Luma.
• Ideogram V4: transparent generation/editing and async option on supported APIs.

Use this map in configuration or validation so a user cannot request “upscale” from a provider that only generates.

Use OpenRouter as a consolidation/fallback path. OpenRouter now supports video, image, and audio. This is useful when you want one credential and one routing layer for multiple modalities, but keep model/provider routing explicit in config. Log the actual model/provider returned where available for cost and quality analysis.

Use Ideogram V4 for asset pipelines. Transparent image generation/editing is useful for product cutouts, overlays, and UI assets. For slow edits, use the async option and poll through the same queued workflow as video. Validate alpha-channel output before publishing to CDN/storage.

Normalize responses at the boundary. TextResponse and FileResponse should be converted into your domain objects immediately: asset record, status, MIME type, dimensions/duration, provider, model, cost metadata if available. Do not let provider response shapes leak into controllers or Blade templates.

Laravel integration tips:

• Store large media on a disk, not in the database.
• Dispatch events such as MediaGenerationStarted, MediaGenerationCompleted, and MediaGenerationFailed.
• Add rate limiting and budget guards per provider/model.
• Use Laravel’s HTTP/client fakes or the package’s test hooks where available; for async polling tests, override protected sleepAsync() instead of injecting a sleep closure.
• Log provider, model, operation, request ID, duration, and failure reason. Video debugging is much easier with operation-level context.

Gotchas and Tips

Breaking change: fromAsync() signature. The third argument changed from ?Closure $sleep to int $timeout for FileResponse and TextResponse.

• Passing a closure or explicit null now fails.
• Named sleep: arguments break.
• Omit the argument for unlimited polling.
• Pass timeout seconds for bounded polling.
• Tests should override protected sleepAsync() instead of passing a sleep closure.
• Retry intervals are now clamped to at least one second, so very aggressive polling tests may behave differently.

Unlimited polling can hang workers. If you omit the timeout, make sure the surrounding job has its own timeout/retry policy and stores enough state to resume or fail cleanly. Prefer explicit timeouts for user-facing requests.

Provider capabilities are uneven. The release adds many video providers, but description, repaint, extension, upscaling, and uncrop are not universally supported. Validate operation/provider combinations before dispatch. Reference-guided repaint is especially provider-dependent.

Provider/model changes can be silent quality changes. OpenRouter routing and Ideogram V4 updates can change outputs even when your code is unchanged. Pin model IDs where possible and keep a small evaluation set for critical image/video pipelines.

Credentials and config caching. After changing provider keys or model defaults, clear and rebuild config cache. In Laravel, a stale config:cache is a common cause of “provider not configured” errors.

Large files need lifecycle rules. Video files are large. Use signed URLs or streamed downloads, set retention policies, and clean up failed/partial generations. Do not load video binaries into memory just to inspect metadata.

Cost and rate limits need application-level controls. Video generation and repaint/upscale operations can be expensive. Add per-user quotas, per-provider rate limits, and idempotency keys so retries do not double-charge.

Async state belongs in your database. Provider handles and file URLs are not enough. Store status, attempt count, deadline, provider, model, operation, and last error so a failed queue worker can be retried safely.

Test the migration explicitly. Add a regression test for any async path that previously passed a sleep closure or null, and update named arguments. This is the most likely place for a 0.6 → 0.7 upgrade to break.