Process API

The Process API enables you to transform existing images with style transfer and edits. Perfect for building content creation tools, media processing pipelines, batch transformations, and creative applications.

For video processing (video editing, motion control), use the Queue API which provides asynchronous job-based processing.

Image

Image Editing

Transform and restyle existing images:

with open("image.jpg", "rb") as image_file:
    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": "Oil painting style with impressionist brushstrokes",
        "data": image_file,
        "enhance_prompt": True,
        "seed": 123,
    })

You can also provide a reference image to guide the edit — for example, to add a specific item:

with open("image.jpg", "rb") as image_file:
    with open("sunglasses.jpg", "rb") as reference_image:
        result = await client.process({
            "model": models.image("lucy-image-2"),
            "prompt": "Add these sunglasses to the person's face",
            "data": image_file,
            "reference_image": reference_image,
        })

Parameters:

prompt (required) - Text description of the style transformation
data (required) - Input image (file object, bytes, or URL)
reference_image (optional) - Reference image to guide the edit (file object, bytes, or URL)
seed (optional) - Random seed for reproducible results
resolution (optional) - Output resolution
enhance_prompt (optional) - Auto-enhance the prompt for better results

Model: lucy-image-2

Input Types

The data and reference_image parameters accept flexible input types:

from typing import Union, Protocol, runtime_checkable
from pathlib import Path

@runtime_checkable
class HasRead(Protocol):
    def read(self) -> Union[bytes, str]: ...

FileInput = Union[HasRead, bytes, str, Path]

Examples:

# Path object (recommended for files)
from pathlib import Path

result = await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "Transform to watercolor style",
    "data": Path("./image.jpg"),
})

# File object from open()
with open("image.jpg", "rb") as file:
    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": "Transform to watercolor style",
        "data": file,
    })

# Bytes
with open("image.jpg", "rb") as f:
    image_bytes = f.read()

result = await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "Transform to watercolor style",
    "data": image_bytes,
})

# URL string
result = await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "Transform this image",
    "data": "https://example.com/image.jpg",
})

The SDK automatically detects whether a string is a file path or URL. Use Path objects for explicit file paths.

Cancellation

Cancel long-running operations using asyncio.Event:

import asyncio

cancel_token = asyncio.Event()

try:
    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": "Epic fantasy landscape with dragons",
        "cancel_token": cancel_token,
    })
except asyncio.CancelledError:
    print("Generation cancelled")

# Cancel the request from another coroutine
cancel_token.set()

You can use this to implement cancel buttons in your UI:

import asyncio

current_cancel_token: asyncio.Event | None = None

async def edit_image(prompt: str):
    global current_cancel_token

    # Cancel previous request if any
    if current_cancel_token:
        current_cancel_token.set()

    current_cancel_token = asyncio.Event()

    result = await client.process({
        "model": models.image("lucy-image-2"),
        "prompt": prompt,
        "data": image_file,
        "cancel_token": current_cancel_token,
    })

    return result

def cancel_generation():
    if current_cancel_token:
        current_cancel_token.set()

Error Handling

The SDK raises specific exception classes for different failure scenarios:

from decart import (
    DecartClient,
    InvalidInputError,
    InvalidAPIKeyError,
    ProcessingError,
    DecartSDKError,
)

try:
    with open("image.jpg", "rb") as image_file:
        result = await client.process({
            "model": models.image("lucy-image-2"),
            "prompt": "Transform this image",
            "data": image_file,
        })
except InvalidInputError as error:
    print(f"Invalid input: {error.message}")
except InvalidAPIKeyError as error:
    print("Invalid API key - check your credentials")
except ProcessingError as error:
    print(f"Processing failed: {error.message}")
except DecartSDKError as error:
    # Catch-all for any other SDK errors
    print(f"SDK error: {error.message}")

Exception Types:

InvalidAPIKeyError - API key is invalid or missing
InvalidBaseURLError - Base URL is malformed
InvalidInputError - Invalid input parameters or validation failed
ProcessingError - Server-side processing error
ModelNotFoundError - Specified model doesn’t exist
DecartSDKError - Base class for all SDK errors

If you provide invalid inputs, you’ll get clear error messages:

# Missing required field
await client.process({
    "model": models.image("lucy-image-2"),
    "prompt": "test",
    # Missing 'data' field
})
# Raises InvalidInputError: Invalid inputs for lucy-image-2: data is required

Import specific exception types for better error handling and type safety.

API Reference

`client.process(options)`

Generate or transform images. Parameters:

options: dict - Configuration dictionary with model and inputs:
- model - Model from models.image()
- cancel_token: asyncio.Event - Optional event for cancellation
- Additional fields depend on the model (see below)

Returns: bytes - The generated/transformed image Inputs by Model:

Image Editing (lucy-image-2)

prompt: str - Style description (required)
data: FileInput - Input image (required)
reference_image: FileInput - Reference image to guide the edit
seed: int - Random seed
resolution: str - Output resolution
enhance_prompt: bool - Auto-enhance prompt

Getting started

Realtime

Non-realtime

Provider Integrations

Libraries & SDKs

Frameworks

Resources

Image

Image Editing

Input Types

Cancellation

Error Handling

API Reference

`client.process(options)`

Next Steps

Queue API

Realtime API

​Image

​Image Editing

​Input Types

​Cancellation

​Error Handling

​API Reference

​client.process(options)

​Next Steps

Queue API

Realtime API

Image

Image Editing

Input Types

Cancellation

Error Handling

API Reference

`client.process(options)`

Next Steps