Perso Interactive On-Device SDK Documentation

Learn how to install and fully configure Perso Interactive iOS SDK.
Explore Perso Interactive On-Device SDK Documentation→

📋 Prerequisites

Requirement	Version
iOS	18.0+
macOS	15.0+
visionOS	2.0+
Swift	6.0+
Xcode	16.0+

📦 Installation (Swift Package Manager)

Open your Xcode project.
Navigate to File > Add Package Dependencies…
Enter the repository URL:

https://github.com/perso-ai/perso-interactive-ondevice-sdk-swift

Select a version or version range.
Choose Add Package.

Once installed, import the SDK:

import PersoInteractiveOnDeviceSDK

🚀 Quick Start

Below is a complete example showing how to initialize the SDK, load models, create a session, display the avatar, and start a conversation.

import PersoInteractiveOnDeviceSDK
// 1. Initialize SDK
PersoInteractive.apiKey = "YOUR_API_KEY"
PersoInteractive.computeUnits = .ane
// 2. Fetch and prepare model-style
let modelStyles = try await PersoInteractive.fetchAvailableModelStyles()
guard let modelStyle = modelStyles.first else {
    return
}
// Download model-style resources if needed
if case .unavailable = modelStyle.availability {
    let stream = PersoInteractive.loadModelStyle(with: modelStyle)
    for try await progress in stream {
        if case .progressing(let value) = progress {
            print("Downloading: \(Int(value.fractionCompleted * 100))%")
        }
    }
}
// 3. Load on-device models
try await PersoInteractive.load()
try await PersoInteractive.warmup()
// 4. Configure audio session (iOS/visionOS only)
#if os(iOS) || os(visionOS)
try PersoInteractive.setAudioSession(
    category: .playAndRecord,
    options: [.defaultToSpeaker, .allowBluetooth]
)
#endif
// 5. Fetch features
let sttModels = try await PersoInteractive.fetchAvailableSTTModels()
let llmModels = try await PersoInteractive.fetchAvailableLLMModels()
let ttsModels = try await PersoInteractive.fetchAvailableTTSModels()
let prompts = try await PersoInteractive.fetchAvailablePrompts()
// 6. Create a session
let session = try await PersoInteractive.createSession(
    for: [
        .speechToText(type: sttModels.first!),
        .largeLanguageModel(llmType: llmModels.first!, promptID: prompts.first!.id),
        .textToSpeech(type: ttsModels.first!)
    ],
    modelStyle: modelStyle,
    statusHandler: { status in
        print("Session status: \(status)")
    }
)
// 7. Display AI Human
let videoView = PersoInteractiveVideoView(session: session)
videoView.videoContentMode = .aspectFit
try videoView.start()
// 8. Start conversation
let userMessage = UserMessage(content: "Hello!")
let stream = session.completeChat(message: userMessage)
for try await message in stream {
    if case .assistant(let assistantMessage, _) = message,
       let chunk = assistantMessage.chunks.last {
        try? videoView.push(text: chunk)
    }
}