> ## 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.

# Process API

> Transform images on-demand

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.

<Note>
  For video processing (video editing, motion control), use the [Queue API](/sdks/python-queue) which provides asynchronous job-based processing.
</Note>

## Image

### Image Editing

Transform and restyle existing images:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:**

```python theme={null}
# 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",
})
```

<Note>The SDK automatically detects whether a string is a file path or URL. Use `Path` objects for explicit file paths.</Note>

## Cancellation

Cancel long-running operations using asyncio.Event:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
# 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
```

<Tip>Import specific exception types for better error handling and type safety.</Tip>

## 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:**

<Accordion title="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
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Queue API" icon="video" href="/sdks/python-queue">
    Asynchronous video processing with job-based queue
  </Card>

  <Card title="Realtime API" icon="bolt" href="/sdks/python-realtime">
    Transform video streams in realtime with WebRTC
  </Card>
</CardGroup>