Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.platform.decart.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Queue API is the primary way to process videos with the JavaScript SDK. Submit jobs that are processed asynchronously in the background, then poll for status and retrieve results when complete.
All video processing (video editing, restyling, motion control) uses the Queue API. For image editing, 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
  • submitAndPoll() - Submit and automatically poll until completion

​
Submit a Job

Submit a video editing job and receive a job ID immediately: 
const job = await client.queue.submit({
  model: models.video("lucy-2.1"),
  data: videoFile,
  prompt: "Transform into anime style",
});

console.log(`Job ID: ${job.job_id}`);
console.log(`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: 
const status = await client.queue.status(job.job_id);

console.log(`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: 
import { writeFileSync } from "fs";

// First check status
const status = await client.queue.status(job.job_id);

if (status.status === "completed") {
  const result = await client.queue.result(job.job_id);

  if (result.status === "completed") {
    // result.data is a Blob
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("output.mp4", buffer);
    console.log("Video saved!");
  } else {
    console.error(`Error: ${result.error}`);
  }
}
Returns:
  • status - Either "completed" or "failed"
  • data - Video Blob (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: 
import { writeFileSync } from "fs";

const result = await client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  prompt: "A serene lake at sunset with mountains in the background",
  resolution: "720p",
  onStatusChange: (job) => {
    console.log(`Status: ${job.status}`);
  },
});

if (result.status === "completed") {
  const buffer = Buffer.from(await result.data.arrayBuffer());
  writeFileSync("output.mp4", buffer);
  console.log("Video saved!");
} else {
  console.error(`Generation failed: ${result.error}`);
}
Parameters:
  • All standard model parameters (prompt, resolution, etc.)
  • onStatusChange (optional) - Callback function called on each status change

​
TypeScript Types

import type {
  JobStatus,
  JobSubmitResponse,
  JobStatusResponse,
  QueueJobResult,
} from "@decartai/sdk";

// Job status values
type JobStatus = "pending" | "processing" | "completed" | "failed";

// Submit response
interface JobSubmitResponse {
  job_id: string;
  status: JobStatus;
}

// Status response
interface JobStatusResponse {
  job_id: string;
  status: JobStatus;
}

// Result (discriminated union)
type QueueJobResult =
  | { status: "completed"; data: Blob }
  | { status: "failed"; error: string };

​
Complete Example

​
Node.js

import { createDecartClient, models } from "@decartai/sdk";
import { writeFileSync } from "fs";

const client = createDecartClient({ apiKey: "your-api-key" });

async function editVideo() {
  console.log("Submitting video editing job...");

  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-2.1"),
    data: videoFile,
    prompt: "Transform into anime style",
    onStatusChange: (job) => {
      console.log(`  Status: ${job.status}`);
    },
  });

  if (result.status === "completed") {
    const buffer = Buffer.from(await result.data.arrayBuffer());
    writeFileSync("cityscape.mp4", buffer);
    console.log("Video saved to cityscape.mp4");
  } else {
    console.error(`Editing failed: ${result.error}`);
  }
}

editVideo();

​
Video Editing with Queue

Transform videos with style transfer: 
import { readFileSync, writeFileSync } from "fs";

const videoBuffer = readFileSync("input-video.mp4");
const videoBlob = new Blob([videoBuffer], { type: "video/mp4" });

const result = await client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  prompt: "Convert to anime style with vibrant colors",
  data: videoBlob,
  onStatusChange: (job) => {
    console.log(`Status: ${job.status}`);
  },
});

if (result.status === "completed") {
  const buffer = Buffer.from(await result.data.arrayBuffer());
  writeFileSync("styled-video.mp4", buffer);
}

​
Cancellation with AbortSignal

Cancel queue operations using AbortController: 
const controller = new AbortController();

// Start generation
const resultPromise = client.queue.submitAndPoll({
  model: models.video("lucy-2.1"),
  prompt: "A beautiful sunset",
  signal: controller.signal,
  onStatusChange: (job) => {
    console.log(`Status: ${job.status}`);
  },
});

// Cancel after 30 seconds (example)
setTimeout(() => {
  controller.abort();
  console.log("Cancellation requested");
}, 30000);

try {
  const result = await resultPromise;
  // Handle result...
} catch (error) {
  if (error.name === "AbortError") {
    console.log("Generation cancelled");
  }
}

​
Manual Polling

For custom polling logic, you can manually poll for status: 
import { writeFileSync } from "fs";

// Submit job
const job = await client.queue.submit({
  model: models.video("lucy-2.1"),
  prompt: "A serene lake at sunset",
});

console.log(`Job submitted: ${job.job_id}`);

// Manual polling loop
while (true) {
  const status = await client.queue.status(job.job_id);
  console.log(`Status: ${status.status}`);

  if (status.status === "completed") {
    const result = await client.queue.result(job.job_id);
    if (result.status === "completed") {
      const buffer = Buffer.from(await result.data.arrayBuffer());
      writeFileSync("output.mp4", buffer);
      console.log("Video saved!");
    }
    break;
  } else if (status.status === "failed") {
    console.error("Generation failed");
    break;
  }

  // Wait before next poll
  await new Promise((r) => setTimeout(r, 2000));
}

​
Error Handling

import {
  createDecartClient,
  models,
  QueueSubmitError,
  QueueStatusError,
  QueueResultError,
  DecartSDKError,
} from "@decartai/sdk";

try {
  const result = await client.queue.submitAndPoll({
    model: models.video("lucy-2.1"),
    prompt: "A beautiful sunset",
  });
} catch (error) {
  if (error instanceof QueueSubmitError) {
    console.error(`Failed to submit job: ${error.message}`);
  } else if (error instanceof QueueStatusError) {
    console.error(`Failed to check status: ${error.message}`);
  } else if (error instanceof QueueResultError) {
    console.error(`Failed to get result: ${error.message}`);
  } else if (error instanceof DecartSDKError) {
    console.error(`SDK error: ${error.message}`);
  }
}

​
Supported Models

All non-realtime video models support queue processing:
ModelTypeDescription
lucy-2.1Video-to-VideoVideo editing (latest)
lucy-2.1-vtonVideo-to-VideoVirtual try-on
lucy-restyle-2Video-to-VideoVideo restyling
lucy-motionImage-to-VideoTrajectory-based motion control
AliasDescription
lucy-latestAlways the latest editing model
lucy-vton-latestAlways the latest virtual try-on model
lucy-restyle-latestAlways the latest restyling model
lucy-clip-latestAlways the latest legacy editing model
lucy-motion-latestAlways the latest motion model
ModelTypeDescription
lucy-clipVideo-to-VideoTransform video style

​
API Reference

​
client.queue.submit(options)

Submit a job for processing. Parameters:
  • options: QueueSubmitOptions - Model and input parameters
    • model - Model from models.video()
    • signal?: AbortSignal - Optional abort signal
    • Additional model-specific parameters
Returns: Promise<JobSubmitResponse>
  • job_id: string - Unique job identifier
  • status: JobStatus - Initial status (“pending”)

​
client.queue.status(jobId)

Check the status of a job. Parameters:
  • jobId: string - The job identifier
Returns: Promise<JobStatusResponse>
  • job_id: string - Job identifier
  • status: JobStatus - Current status

​
client.queue.result(jobId)

Get the result of a completed job. Parameters:
  • jobId: string - The job identifier
Returns: Promise<QueueJobResult>
  • When completed: { status: "completed", data: Blob }
  • When failed: { status: "failed", error: string }

​
client.queue.submitAndPoll(options)

Submit a job and poll until completion. Parameters:
  • options: QueueSubmitAndPollOptions - Model and input parameters
    • onStatusChange?: (job: JobStatusResponse) => void - Status change callback
    • signal?: AbortSignal - Optional abort signal
    • Additional model-specific parameters
Returns: Promise<QueueJobResult>

​
Next Steps

Process API

Synchronous image editing

Realtime API

Transform video streams in realtime with WebRTC