Lucy Restyle Long-Form User Guide

Restyling Extended Video with a Single API Call

Applying consistent style transformations across extended video footage has historically required either frame-by-frame manual editing or dedicated GPU infrastructure. Lucy Restyle from Decart addresses this constraint directly, processing videos up to 30 minutes while preserving motion coherence and visual detail through fal infrastructure.

The technical challenge is substantial. Video style transfer models typically struggle with temporal consistency, producing flickering artifacts or gradual style drift as frame count increases¹. Traditional approaches process frames independently, leading to visible discontinuities when adjacent frames receive slightly different treatments.

Lucy Restyle solves this by maintaining coherent aesthetic application across thousands of frames, accepting a source video and text prompt while handling the computational complexity internally. This guide covers environment setup, request construction, webhook integration, and production optimization.

API Specifications

Lucy Restyle operates as a video-to-video model designed for extended content. The API accepts your source video through fal infrastructure and applies text-guided transformations while preserving the original motion, timing, and narrative structure.

Parameter	Specification
Maximum Duration	30 minutes
Output Resolution	720p
Pricing	$0.01 per second of source video
Accepted Formats	mp4, mov, webm, m4v, gif
Output Format	MP4 with H.264 encoding

The required parameters are minimal: prompt (text description of desired style) and video_url (publicly accessible URL to your source video).

Optional parameters include:

seed (integer): Enables reproducible results. Same seed with identical inputs produces consistent output.
resolution (enum): Currently supports 720p only.
enhance_prompt (boolean, default: true): Automatically enriches your prompt for improved results.
sync_mode (boolean, default: false): When true, the request blocks until processing completes and returns the video URL directly.

fal^{MODEL APIs}

The fastest, cheapest and most reliable way to run genAI models. 1 API, 100s of models

Build

fal^SERVERLESS

Scale custom models and apps to thousands of GPUs instantly

Deploy

fal^COMPUTE

A fully controlled GPU cloud for enterprise AI training + research

Train

Environment Setup

Install the fal client for your environment:

# Python
pip install fal-client

# JavaScript
npm install --save @fal-ai/client

Set your API key as an environment variable:

export FAL_KEY='your-api-key-here'

The quickstart documentation covers additional configuration options.

Basic Implementation

The recommended approach uses fal.subscribe, which handles queue status updates and returns the result when processing completes:

import { fal } from "@fal-ai/client";

const result = await fal.subscribe("decart/lucy-restyle", {
  input: {
    prompt: "1980s VHS aesthetic with tracking lines and color bleeding",
    video_url: "https://your-storage.com/source-video.mp4",
  },
  logs: true,
  onQueueUpdate: (update) => {
    if (update.status === "IN_PROGRESS") {
      update.logs.map((log) => log.message).forEach(console.log);
    }
  },
});

console.log(result.data.video.url);

The onQueueUpdate callback surfaces processing status, preventing uncertainty during long-running operations. For a 10-minute video at $0.01/second, expect approximately $6.00 per transformation.

Webhook Integration

For production systems processing extended videos, webhook-based architecture avoids long-polling and handles results asynchronously. Submit requests with a webhook URL:

import { fal } from "@fal-ai/client";

const { request_id } = await fal.queue.submit("decart/lucy-restyle", {
  input: {
    prompt: "Oil painting with visible brushstrokes",
    video_url: "https://your-storage.com/source-video.mp4",
  },
  webhookUrl: "https://your-server.com/api/fal-webhook",
});

// Store request_id for tracking

Your webhook endpoint receives the completed result, allowing your application to continue processing without maintaining open connections. The webhooks documentation covers payload structure and verification.

Error Handling

Video processing introduces multiple failure points. Implement structured exception handling with specific error cases:

import fal_client

try:
    result = fal_client.subscribe(
        "decart/lucy-restyle",
        arguments={
            "prompt": "Watercolor painting style",
            "video_url": video_url
        },
        timeout=1800  # 30 minutes for long videos
    )
except Exception as e:
    error_msg = str(e).lower()
    if "video_url" in error_msg:
        print("Video URL is invalid or inaccessible")
    elif "timeout" in error_msg:
        print("Processing exceeded timeout")
    elif "rate limit" in error_msg:
        print("Rate limit exceeded, implement backoff")
    else:
        print(f"API error: {e}")

Validate video URLs before submission. Verify files exist, are publicly accessible, and use supported formats (mp4, mov, webm, m4v, gif).

Cost Optimization

With pricing at $0.01 per second, a 30-minute video costs $18.00 per transformation. Consider these strategies:

Trim unnecessary footage: Remove intro/outro sections before processing. A 20-minute video costs $6.00 less than a 30-minute video.
Test on short clips first: Validate prompt effectiveness on 30-60 second segments before committing to full-length processing.
Cache results: Store output URLs associated with input parameters. Check existing results before making API calls.
Use seed values for variations: When exploring alternatives, modify the seed rather than the prompt to explore the model's creative space efficiently.

Rate Limiting

fal implements rate limiting for fair resource allocation. For high-volume applications, implement exponential backoff when encountering rate limit errors. A common pattern involves retrying with progressively longer delays (5 seconds, 10 seconds, 20 seconds) before failing permanently.

For sustained high volume, implement a queue system that accepts user requests into a database, then processes with controlled concurrency. This prevents rate limit issues and provides visibility into your processing pipeline. See the FAQ for rate limit specifications.

Prompt Engineering

Effective prompts drive output quality. Lucy Restyle responds well to specific, visual descriptions referencing concrete aesthetics rather than abstract concepts.

Approach	Example
Vague	"Make it artistic"
Specific	"Oil painting with visible brushstrokes and swirling textures"
Vague	"Vintage look"
Specific	"1970s film stock with warm tones, slight grain, and soft focus"

Reference specific art movements, film stocks, historical periods, or named visual styles. The enhance_prompt feature assists interpretation, but clear initial intent produces superior results. The model processes your creative direction into detailed style parameters internally.

Integration Patterns

Content Platforms: Users upload videos through your interface. Store in cloud storage (S3, GCS, or similar), generate a signed URL with appropriate expiration, pass to Lucy Restyle with a webhook endpoint, and return processed video to storage upon completion. Associate output URLs with user accounts for retrieval.

Automated Workflows: Trigger restyling via webhooks when new content arrives. Generate multiple style variations automatically, allowing users to preview options before selecting their preferred version. This pattern works well for content management systems processing user-generated video.

Preview Systems: Process short clips (30-60 seconds) with sync_mode: true for near-immediate feedback on style choices. Once approved, process full-length video asynchronously via webhook. This two-stage approach reduces wasted API spend on rejected styles.

Production Monitoring

Track key metrics for production deployments: success rate, average processing time by video length, cost per transformation, and output quality relative to expectations.

Log all requests with parameters, response times, and outcomes. This audit trail identifies patterns when issues arise, such as certain prompt types producing unexpected results or specific video characteristics causing failures.

Audio Handling

Lucy Restyle processes the visual track only. Audio from the source video is not included in the output. If your application requires audio, implement a post-processing step to extract audio from the original and merge it with the restyled video using FFmpeg. fal provides FFmpeg utility APIs for video composition if you prefer API-based processing.

File Uploads

For videos not already hosted at a public URL, use fal.storage.upload() to upload before processing. The client returns a URL suitable for the video_url parameter. The client also auto-uploads binary objects passed directly to input fields, though explicit upload provides more control for reusing URLs across multiple transformations.

Next Steps

Start with simple transformations on short videos to understand model behavior. Experiment with different prompts to develop intuition for effective configurations. As confidence builds, scale to longer content with webhook-based architecture for production reliability.