xmax_sdk - Dart API docs

We introduce XmaxSDK, a Flutter SDK designed for real-time interactive video generation via Xmax models. XmaxSDK implements an end-to-end pipeline covering media acquisition, video streaming, frame-by-frame generation, and on-device rendering, enabling developers to seamlessly integrate low-latency, high-fidelity video transformations into creative applications at a much lower cost than alternative solutions.

X-Lab realtime generation demo X-Lab index demo X-Lab storage demo

What you can build with XmaxSDK

Realtime Use Case	Description	Demo
Character Swapping	Replace anyone in your live feed with a designated avatar in real time.	_{▶ Play demo}
Character Swapping	Prompt: `视频中角色替换成参考图中角色` Reference image: Select a clear image of the desired character with a clean background.	_{▶ Play demo}
Virtual Try-On	Seamlessly change outfits, preserving exact body shape, natural motion, and an authentic fit.	_{▶ Play demo}
Virtual Try-On	Prompt: `视频中人物衣服替换成参考图中衣服` Reference image: Select a clear image of the target outfit with a clean background.	_{▶ Play demo}
Video Restyling	Reimagine your world in any style with an immersive visual experience.	_{▶ Play demo}
Video Restyling	Prompt: `视频风格变为参考图指定的风格` Reference image: Select an image that captures the artistic style you want to apply.	_{▶ Play demo}
AI Companions	Summon virtual characters into your live camera feed and interact with them through gestures.	_{▶ Play demo}
AI Companions	Prompt: `指定角色在场景中互动` Reference image: Select a clear image of the virtual character you want to summon with a clean background.	_{▶ Play demo}

Why XmaxSDK?

Low latency	Cost efficiency	High fidelity
End-to-end latency is measured in , ensuring that updates to generation conditions and interaction controls are reflected instantly.	Run on a , reducing inference costs by orders of magnitude versus datacenter GPUs like H100.	Our models support real-time generation at up to , delivering production-ready, high-quality video output.

Prerequisites

Flutter 3.35 or later
Dart 3.9 or later
iOS 15.0 or later, or Android API 26 or later
Java 17 for Android builds
An Xmax API key

Warning

Never commit your Xmax API key to version control. Pass it securely at runtime or use short-lived temporary keys issued by the Xmax API. For step-by-step instructions, see Authentication.

Installation

flutter pub add xmax_sdk:1.1.0

Host Configuration

iOS

Set the deployment target to iOS 15.0 or later. For CocoaPods integration, use the standard CocoaPods CDN source in ios/Podfile:

source 'https://cdn.cocoapods.org/'

platform :ios, '15.0'

target 'Runner' do
  use_frameworks!

  # Keep the Flutter pod installation generated by the Flutter template here.
end

Enable camera and optional microphone permission handlers in the existing post_install block:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
        '$(inherited)',
        'PERMISSION_CAMERA=1',
        'PERMISSION_MICROPHONE=1',
      ]
    end
  end
end

Add a camera usage description to ios/Runner/Info.plist. Include the microphone description if your app enables microphone input:

<key>NSCameraUsageDescription</key>
<string>This app uses the camera for real-time video input.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone for real-time audio input.</string>

Customize this message to match your application's user experience. XmaxSDK automatically requests camera access when creating the video stream. With useMicrophone: true, it also requests microphone access. Stream creation fails with an XmaxError if a required permission is denied or unavailable.

See the complete example/ios/Podfile for a working setup.

With Swift Package Manager, the permission plugin derives its enabled permissions from the usage descriptions in Info.plist. After adding a permission, refresh the Swift package manifest and the app's derived build caches once, then rebuild; an existing cached configuration can otherwise keep that permission disabled.

Android

Set the application's minimum SDK to 26 and compile with Java 17 in android/app/build.gradle.kts:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    defaultConfig {
        minSdk = 26
    }
}

Use the standard Google and Maven Central dependency repositories in android/build.gradle.kts:

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

Also make it available while Flutter plugins are resolved in android/settings.gradle.kts:

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

Enable AndroidX and Jetifier in android/gradle.properties:

android.useAndroidX=true
android.enableJetifier=true

Declare the required permissions in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

RECORD_AUDIO is required only when using useMicrophone: true. External sources can submit their own PCM audio without microphone permission. The example's AndroidManifest.xml removes unused capabilities during manifest merging.

Release builds with R8 must also suppress warnings for optional device and serializer APIs referenced by Tencent COS. Add the following rules to the host application's Release ProGuard configuration:

-dontwarn java.awt.**
-dontwarn javax.money.**
-dontwarn com.google.common.collect.ArrayListMultimap
-dontwarn com.google.common.collect.Multimap
-dontwarn org.javamoney.moneta.**
-dontwarn org.joda.time.**
-dontwarn springfox.documentation.spring.web.json.Json

The same configuration is available in the example's proguard-rules.pro.

Quick Start

Use your front camera to turn yourself into a character from a reference image in real time.

import 'package:xmax_sdk/xmax_sdk.dart';

// Initialize the client
final client = XmaxClient(configuration: XmaxConfiguration(
  apiKey: '<YOUR_XMAX_API_KEY>',
  environment: XmaxEnvironment.global,
));

// Initialize the realtime manager
final realtime = client.createRealtimeManager(
  options: const RealtimeConfiguration(model: RealtimeModel.x2_1),
);

// Create the video view
// Declare tracks in the page State and use buildVideoView() in build()
RealtimeVideoTrack? localTrack;
RealtimeVideoTrack? remoteTrack;
XmaxRealtimeDualVideo buildVideoView() => XmaxRealtimeDualVideo(
  localTrack: localTrack,
  remoteTrack: remoteTrack,
);

// Create a camera stream and bind the preview
final localStream = await realtime.createLocalCameraStream(
  position: CameraPosition.front,
);
setState(() => localTrack = localStream.videoTrack);

// Once the preview is ready, start generation and display the result
final remoteStream = await realtime.startGeneration(
  localStream: localStream,
  context: RealtimeContext(
    prompt: "视频中角色替换成参考图中角色",
    referencePath: "https://cdn.xmax.ai/images/playground/charx/charx_image1.png?v=26&presetVersion=20261022",
  ),
);
setState(() => remoteTrack = remoteStream?.videoTrack);

// Run the following when generation is no longer needed
await realtime.close();

Example Project

A complete example application for both iOS and Android is available in example. It demonstrates real-time generation using live camera feeds and video files.

X-Lab home X-Lab SDK features X-Lab storage service X-Lab realtime generation X-Lab trajectory generation