Queue API

Asynchronous job-based video processing

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:

Status	Description
pending	Job is queued, waiting to be processed
processing	Job is currently being processed
completed	Job finished successfully
failed	Job 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:

Model	Type	Description
lucy-2.1	Video-to-Video	Video editing (latest)
lucy-vton-3	Video-to-Video	Virtual try-on (latest)
lucy-restyle-2	Video-to-Video	Video restyling

Latest aliases

Alias	Description
lucy-latest	Always the latest editing model
lucy-vton-latest	Always the latest virtual try-on model
lucy-restyle-latest	Always the latest restyling model
lucy-clip-latest	Always the latest legacy editing model

Previous generation models

Model	Type	Description
lucy-clip	Video-to-Video	Transform video style
lucy-vton-2	Video-to-Video	Virtual try-on (previous)

---

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