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

# Overview

> A Swift SDK for Decart's models on iOS and macOS

<Card title="GitHub" icon="github" href="https://github.com/DecartAI/decart-ios">
  View source code and contribute
</Card>

## Installation

### Swift Package Manager

Add the package dependency in Xcode:

1. File → Add Package Dependencies
2. Enter: `https://github.com/decartai/decart-ios`
3. Select version and add to your target

Or add to your `Package.swift`:

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/decartai/decart-ios.git", from: "0.6.0")
]
```

## Quick Start

```swift theme={null}
import Foundation
import DecartSDK

let config = DecartConfiguration(apiKey: "your-api-key-here")
let client = DecartClient(decartConfiguration: config)

// Edit a video using the Queue API
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 data):
    try data.write(to: outputURL)
    print("Video saved!")
case .failed(_, let error):
    print("Failed: \(error)")
}
```

## What can you build?

The SDK provides three main APIs for different use cases:

| If you need to...                         | Use          | Main class              |
| ----------------------------------------- | ------------ | ----------------------- |
| Transform live camera streams over WebRTC | Realtime API | `DecartRealtimeManager` |
| Generate/edit videos asynchronously       | Queue API    | `QueueClient`           |
| Edit images synchronously                 | Process API  | `ProcessClient`         |

<CardGroup cols={3}>
  <Card title="Realtime API" href="/sdks/swift-realtime">
    Realtime video streams
  </Card>

  <Card title="Queue API" href="/sdks/swift-queue">
    Video processing
  </Card>

  <Card title="Process API" href="/sdks/swift-process">
    Image editing
  </Card>
</CardGroup>

## Client Setup

Initialize the Decart client with your API key:

```swift theme={null}
import DecartSDK

let config = DecartConfiguration(
    baseURL: "https://api.decart.ai",  // optional, this is the default
    apiKey: "your-api-key-here"
)

let client = DecartClient(decartConfiguration: config)
```

**Parameters:**

* `baseURL` (optional) - Custom API endpoint (defaults to `https://api.decart.ai`)
* `apiKey` (required) - Your Decart API key from the [platform](https://platform.decart.ai)

<Warning>
  Store your API key securely. Never commit API keys to version control. Use environment variables or secure storage like Keychain.
</Warning>

## Client Tokens

For production iOS and macOS apps using the Realtime API, fetch short-lived client tokens from your backend instead of embedding your permanent API key in the app bundle:

```swift theme={null}
// Fetch ephemeral key from your backend
let ephemeralKey = try await fetchTokenFromBackend()

// Use it to create the client
let config = DecartConfiguration(apiKey: ephemeralKey)
let client = DecartClient(decartConfiguration: config)
```

<Tip>
  See [Client Tokens](/getting-started/client-tokens) for details on secure client-side authentication.
</Tip>

## Available Models

Import models from the SDK to use with any API:

```swift theme={null}
import DecartSDK

// Realtime models
Models.realtime(.lucy2_1)                 // Realtime video editing (latest)
Models.realtime(.lucy2_1_vton)            // Virtual try-on
Models.realtime(.lucyRestyle2)            // Realtime video restyling

// Video models (Queue API)
Models.video(.lucy2_1)                    // Video editing (latest)
Models.video(.lucy2_1_vton)              // Virtual try-on
Models.video(.lucyRestyle2)               // Video restyling
Models.video(.lucyMotion)                 // Trajectory-based motion control

// Image models (Process API)
Models.image(.lucyImage2)                 // Image editing

// Latest aliases — always point to the newest version
Models.realtime(.lucyLatest)              // Latest realtime editing model
Models.video(.lucyLatest)                 // Latest video editing model
Models.video(.lucyVtonLatest)            // Latest virtual try-on model
Models.image(.lucyImageLatest)            // Latest image editing model
```

<Accordion title="Previous generation models">
  ```swift theme={null}
  // Realtime models
  Models.realtime(.lucy)    // Realtime video editing
  Models.realtime(.lucy_restyle)              // Realtime video transformation

  // Video models
  Models.video(.lucy_clip)           // Lucy Clip
  ```
</Accordion>

Each model exposes properties for optimal configuration:

```swift theme={null}
let model = Models.realtime(.lucy-restyle-2)
print(model.fps)     // 22
print(model.width)   // 1280
print(model.height)  // 704
```

## Platform Requirements

<Note>
  The Swift SDK requires:

  * **iOS 17.0+** or **macOS 12.0+**
  * **Swift 6.2+**
  * **Xcode 16.0+**
  * A **real device** for camera access (simulator not supported for WebRTC camera features)
</Note>

## Swift Concurrency

The SDK uses modern Swift concurrency with async/await and `AsyncStream` for reactive state:

```swift theme={null}
// All connection methods are async
let remoteStream = try await manager.connect(localStream: localStream)

// Monitor state changes with AsyncStream
for await state in manager.events {
    print("Connection: \(state.connectionState)")
    print("Service: \(state.serviceStatus)")
}
```

## Type Safety

The SDK uses typed input classes for each model, providing compile-time guarantees:

```swift theme={null}
// Video editing — requires prompt + video data
let videoEditInput = try VideoEditInput(
    prompt: "Transform into anime style",
    data: .video(data: videoData)
)

// Image editing — requires prompt + image data
let imageInput = try ImageToImageInput(
    prompt: "Change the background to a beach",
    data: .image(data: imageData)
)

// Video restyling — requires prompt OR reference image (not both)
let restyleInput = try VideoRestyleInput(
    prompt: "Studio Ghibli style",
    data: .video(data: videoData)
)
```

## Ready to start building?

<CardGroup cols={3}>
  <Card title="Realtime API Guide" href="/sdks/swift-realtime">
    **Build realtime iOS experiences**

    Camera handling, video transformation, and interactive applications with WebRTC.
  </Card>

  <Card title="Queue API Guide" href="/sdks/swift-queue">
    **Video processing**

    Edit videos, control motion, and transform videos with style transfer.
  </Card>

  <Card title="Process API Guide" href="/sdks/swift-process">
    **Image editing**

    Edit and transform images on-demand with synchronous processing.
  </Card>
</CardGroup>