Queue API

Asynchronous job-based video processing

The Queue API is the primary way to process videos with the Swift 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 is accessed via client.queue and 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:

import Foundation
import DecartSDK

let videoData = try Data(contentsOf: videoURL)
let input = try VideoEditInput(
    prompt: "Transform into anime style",
    data: .video(data: videoData)
)

let job = try await client.queue.submit(model: .lucy_2, input: input)

print("Job ID: \(job.jobId)")
print("Status: \(job.status)")  // .pending

Returns:

• jobId - Unique identifier for the job
• status - Initial status (.pending)

---

Check Job Status

Poll the status of a submitted job:

let status = try await client.queue.status(jobId: job.jobId)

print("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

---

Get Job Result

Retrieve the video data once the job is completed:

let status = try await client.queue.status(jobId: job.jobId)

if status.status == .completed {
    let videoData = try await client.queue.result(jobId: job.jobId)
    try videoData.write(to: outputURL)
}

Returns: Data — the raw video bytes

---

Submit and Poll

The easiest way to use the Queue API — submit a job and automatically poll until completion:

let videoData = try Data(contentsOf: videoURL)
let input = try VideoEditInput(
    prompt: "Transform into anime style",
    data: .video(data: videoData)
)

let result = try await client.queue.submitAndPoll(
    model: .lucy_2,
    input: input
) { status in
    print("Status: \(status.status)")
}

switch result {
case .completed(let jobId, let data):
    try data.write(to: outputURL)
    print("Video saved!")
case .failed(let jobId, let error):
    print("Failed: \(error)")
}

Parameters:

• model (required) - Video model from Models.video()
• input (required) - Typed input for the model
• onStatusChange (optional) - Closure called on each status change

Returns: QueueJobResult

• .completed(jobId: String, data: Data) - Video data on success
• .failed(jobId: String, error: String) - Error message on failure

---

Video Editing

Transform videos with prompt and optional reference image using lucy_2:

let input = try VideoEditInput(
    prompt: "Convert to anime style with vibrant colors",
    data: .video(data: videoData),
    referenceImage: .image(data: refImageData),  // optional
    resolution: .res720p
)

let result = try await client.queue.submitAndPoll(
    model: .lucy_2,
    input: input
)

VideoEditInput parameters:

• prompt (required) - Text description of the transformation
• data (required) - Input video as FileInput
• referenceImage (optional) - Reference image as FileInput
• seed (optional) - Random seed for reproducible results
• resolution (optional) - Output resolution (.res720p or .res480p)
• enhancePrompt (optional) - Auto-enhance the prompt

---

Video Restyling

Restyle videos using either a text prompt or a reference image (but not both) with lucy_restyle_2:

// Option A: With text prompt
let promptInput = try VideoRestyleInput(
    prompt: "Studio Ghibli style",
    data: .video(data: videoData)
)

// Option B: With reference image
let imageInput = try VideoRestyleInput(
    data: .video(data: videoData),
    referenceImage: .image(data: refImageData)
)

let result = try await client.queue.submitAndPoll(
    model: .lucy_restyle_2,
    input: promptInput  // or imageInput
)

VideoRestyleInput parameters:

• prompt (optional) - Text description of style (required if no referenceImage)
• data (required) - Input video as FileInput
• referenceImage (optional) - Reference image (required if no prompt)
• seed (optional) - Random seed
• resolution (optional) - Output resolution
• enhancePrompt (optional) - Auto-enhance the prompt

You must provide either prompt or referenceImage, but not both. The SDK validates this at initialization.

---

Manual Polling

For custom polling logic, use submit(), status(), and result() separately:

import Foundation

// Submit job
let job = try await client.queue.submit(model: .lucy_2, input: input)
print("Job submitted: \(job.jobId)")

// Manual polling loop
while true {
    let status = try await client.queue.status(jobId: job.jobId)
    print("Status: \(status.status)")

    switch status.status {
    case .completed:
        let data = try await client.queue.result(jobId: job.jobId)
        try data.write(to: outputURL)
        print("Video saved!")
        return
    case .failed:
        print("Processing failed")
        return
    default:
        try await Task.sleep(for: .seconds(2))
    }
}

---

Error Handling

do {
    let result = try await client.queue.submitAndPoll(
        model: .lucy_2,
        input: input
    )
} catch let error as DecartError {
    switch error {
    case .invalidAPIKey:
        print("Invalid API key")
    case .invalidInput(let message):
        print("Invalid input: \(message)")
    case .queueError(let message):
        print("Queue error: \(message)")
    case .networkError(let underlying):
        print("Network error: \(underlying)")
    case .serverError(let message):
        print("Server error: \(message)")
    default:
        print("Error: \(error.localizedDescription)")
    }
}

---

Supported Models

All video models support queue processing:

Model	Type	Description
lucy2_1	Video-to-Video	Video editing (latest)
lucy2_1_vton	Video-to-Video	Virtual try-on (first generation)
lucyRestyle2	Video-to-Video	Video restyling with prompt or reference image
lucyMotion	Image-to-Video	Trajectory-based motion control

Previous generation models

Model	Type	Description
lucy_clip	Video-to-Video	Transform video style

---

API Reference

client.queue.submit(model:input:)

Submit a job for processing.

Parameters:

• model: VideoModel - Video model
• input - Typed input (VideoEditInput, VideoRestyleInput, or VideoToVideoInput)

Returns: JobSubmitResponse

• jobId: 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: JobStatusResponse

• jobId: 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: Data - Video bytes

---

client.queue.submitAndPoll(model:input:onStatusChange:)

Submit a job and poll until completion.

Parameters:

• model: VideoModel - Video model
• input - Typed input
• onStatusChange: ((JobStatusResponse) -> Void)? - Optional status callback

Returns: QueueJobResult

---

Next Steps

Process API

Synchronous image editing

Realtime API

Transform video streams in realtime with WebRTC