Skip to main content
The Queue API is the primary way to generate videos with the Python SDK. Submit jobs that are processed asynchronously in the background, then poll for status and retrieve results when complete.
All video generation (text-to-video, image-to-video, video-to-video, motion control) uses the Queue API. For image generation, use the Process API.

​
Overview

The Queue API provides four main methods:
  • submit() - Submit a job and get a job ID immediately
  • status() - Check the status of a submitted job
  • result() - Retrieve the completed video
  • submit_and_poll() - Submit and automatically poll until completion

​
Submit a Job

Submit a video generation job and receive a job ID immediately: 
job = await client.queue.submit({
    "model": models.video("lucy-pro-t2v"),
    "prompt": "A serene lake at sunset with mountains in the background",
    "resolution": "720p",
})

print(f"Job ID: {job.job_id}")
print(f"Status: {job.status}")  # "pending"
Returns:
  • job_id - Unique identifier for the job
  • status - Initial status ("pending")

​
Check Job Status

Poll the status of a submitted job: 
status = await client.queue.status(job.job_id)

print(f"Status: {status.status}")  # "pending", "processing", "completed", or "failed"
Status Values:
StatusDescription
pendingJob is queued, waiting to be processed
processingJob is currently being processed
completedJob finished successfully
failedJob failed or timed out (timeout after 10 minutes)

​
Get Job Result

Retrieve the video once the job is completed: 
# First check status
status = await client.queue.status(job.job_id)

if status.status == "completed":
    result = await client.queue.result(job.job_id)

    if result.status == "completed":
        with open("output.mp4", "wb") as f:
            f.write(result.data)
    else:
        print(f"Error: {result.error}")
Returns:
  • status - Either "completed" or "failed"
  • data - Video bytes (when completed)
  • error - Error message (when failed)

​
Submit and Poll

The easiest way to use the Queue API - submit a job and automatically poll until completion: 
result = await client.queue.submit_and_poll({
    "model": models.video("lucy-pro-t2v"),
    "prompt": "A serene lake at sunset with mountains in the background",
    "resolution": "720p",
    "on_status_change": lambda job: print(f"Status: {job.status}"),
})

if result.status == "completed":
    with open("output.mp4", "wb") as f:
        f.write(result.data)
else:
    print(f"Generation failed: {result.error}")
Parameters:
  • All standard model parameters (prompt, resolution, etc.)
  • on_status_change (optional) - Callback function called on each status change

​
Complete Example

import asyncio
from decart import DecartClient, models

async def generate_video():
    async with DecartClient(api_key="your-api-key") as client:
        print("Submitting video generation job...")

        result = await client.queue.submit_and_poll({
            "model": models.video("lucy-pro-t2v"),
            "prompt": "A futuristic cityscape with flying cars",
            "resolution": "720p",
            "on_status_change": lambda job: print(f"  Status: {job.status}"),
        })

        if result.status == "completed":
            with open("cityscape.mp4", "wb") as f:
                f.write(result.data)
            print("Video saved to cityscape.mp4")
        else:
            print(f"Generation failed: {result.error}")

asyncio.run(generate_video())
Output: 
Submitting video generation job...
  Status: pending
  Status: processing
  Status: completed
Video saved to cityscape.mp4

​
Image Animation with Queue

Animate images using the queue for better control: 
with open("image.jpg", "rb") as image_file:
    result = await client.queue.submit_and_poll({
        "model": models.video("lucy-pro-i2v"),
        "prompt": "Animate with gentle motion and wind",
        "data": image_file,
        "resolution": "720p",
        "on_status_change": lambda job: print(f"Status: {job.status}"),
    })

​
Video Editing with Queue

Transform videos with style transfer: 
with open("input.mp4", "rb") as video_file:
    result = await client.queue.submit_and_poll({
        "model": models.video("lucy-pro-v2v"),
        "prompt": "Convert to anime style with vibrant colors",
        "data": video_file,
        "on_status_change": lambda job: print(f"Status: {job.status}"),
    })

​
Manual Polling

For custom polling logic, you can manually poll for status: 
import asyncio

# Submit job
job = await client.queue.submit({
    "model": models.video("lucy-pro-t2v"),
    "prompt": "A serene lake at sunset",
})

print(f"Job submitted: {job.job_id}")

# Manual polling loop
while True:
    status = await client.queue.status(job.job_id)
    print(f"Status: {status.status}")

    if status.status == "completed":
        result = await client.queue.result(job.job_id)
        with open("output.mp4", "wb") as f:
            f.write(result.data)
        print("Video saved!")
        break
    elif status.status == "failed":
        print("Generation failed")
        break

    # Wait before next poll
    await asyncio.sleep(2)

​
Error Handling

from decart import (
    DecartClient,
    QueueSubmitError,
    QueueStatusError,
    QueueResultError,
    DecartSDKError,
)

try:
    result = await client.queue.submit_and_poll({
        "model": models.video("lucy-pro-t2v"),
        "prompt": "A beautiful sunset",
    })
except QueueSubmitError as error:
    print(f"Failed to submit job: {error.message}")
except QueueStatusError as error:
    print(f"Failed to check status: {error.message}")
except QueueResultError as error:
    print(f"Failed to get result: {error.message}")
except DecartSDKError as error:
    print(f"SDK error: {error.message}")

​
Supported Models

All non-realtime video models support queue processing:
ModelTypeDescription
lucy-pro-t2vText-to-VideoGenerate videos from text prompts
lucy-pro-i2vImage-to-VideoAnimate images
lucy-dev-i2vImage-to-VideoDevelopment model for animation
lucy-pro-v2vVideo-to-VideoTransform video style
lucy-fast-v2vVideo-to-VideoFast video transformation

​
API Reference

​
client.queue.submit(options)

Submit a job for processing. Parameters:
  • options: dict - Model and input parameters
Returns: JobSubmitResponse
  • job_id: str - Unique job identifier
  • status: str - Initial status (“pending”)

​
client.queue.status(job_id)

Check the status of a job. Parameters:
  • job_id: str - The job identifier
Returns: JobStatusResponse
  • job_id: str - Job identifier
  • status: str - Current status

​
client.queue.result(job_id)

Get the result of a completed job. Parameters:
  • job_id: str - The job identifier
Returns: QueueJobResult
  • status: str - “completed” or “failed”
  • data: bytes - Video data (when completed)
  • error: str - Error message (when failed)

​
client.queue.submit_and_poll(options)

Submit a job and poll until completion. Parameters:
  • options: dict - Model and input parameters
    • on_status_change: Callable (optional) - Status change callback
Returns: QueueJobResult

​
Next Steps

Process API

Synchronous image generation

Realtime API

Transform video streams in realtime with WebRTC