xmax_sdk 1.0.5

Flutter SDK for integrating Xmax AI real-time interactive video generation and media storage into iOS and Android apps.

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.

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

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

XmaxSDK is published on pub.dev and can also be integrated from a Git revision or a local source checkout.

pub.dev

Add XmaxSDK to your application's pubspec.yaml:

dependencies:
  xmax_sdk: ^1.0.5

Git

To use a release tag or commit directly from GitHub:

dependencies:
  xmax_sdk:
    git:
      url: https://github.com/Xmax-AI/XmaxSDK-Flutter.git
      ref: 1.0.5

Local path

To use a local source checkout during development:

dependencies:
  xmax_sdk:
    path: ../XmaxSDK

Install the dependencies:

flutter pub get

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

Complete the host configuration before running these examples.

Create a client

Create a client and a realtime manager for your screen. This example uses the China service; for the global service, use XmaxEnvironment.global and RealtimeModel.x2_1_1_preview_us.

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:xmax_sdk/xmax_sdk.dart';

final client = XmaxClient(
  configuration: XmaxConfiguration(apiKey: 'YOUR_XMAX_API_KEY'),
);
late final realtime = client.createRealtimeManager(
  options: const RealtimeConfiguration(
    model: RealtimeModel.x2_1_1_preview_cn,
  ),
);

Generate and display video

Keep the manager and streams in your widget's state, and display the local track before starting generation. XmaxRealtimeDualVideo switches from preview to the generated video when its first frame is ready.

RealtimeMediaStream? localStream;
RealtimeMediaStream? remoteStream;

Future<void> startGeneration() async {
  final local = await realtime.createLocalCameraStream();
  if (!mounted) return;
  setState(() => localStream = local);

  final remote = await realtime.startGeneration(
    localStream: local,
    context: RealtimeContext(
      prompt: '视频中角色替换成参考图中角色',
      referencePath:
          'https://platform.xmaxai.com/images/source/charx/chatx_image1.jpg',
    ),
  );
  if (!mounted) return;
  setState(() => remoteStream = remote);
}

@override
Widget build(BuildContext context) {
  final local = localStream;
  if (local == null) {
    return const Center(child: CircularProgressIndicator());
  }

  return XmaxRealtimeDualVideo(
    localTrack: local.videoTrack,
    remoteTrack: remoteStream?.videoTrack,
  );
}

Listen for events

Register listeners before creating the input stream. Observe state changes and runtime failures through setStateListener, and handle errors from awaited calls with try / catch.

await realtime.setStateListener((state) {
  debugPrint('State: ${state.connectionState.value}');
  final error = state.reason?.error;
  if (error != null) {
    debugPrint('Error: ${error.code.value} ${error.message}');
  }
});

Resource cleanup

Use disconnect() to stop generation while keeping the local preview active:

await realtime.disconnect();

Call close() when leaving the screen to release all SDK resources; there is no need to disconnect first.

@override
void dispose() {
  unawaited(realtime.close());
  super.dispose();
}

Upload a reference image

RealtimeContext.referencePath accepts a remote image URL. Upload a local image through the storage manager and pass the returned URL as the reference.

final storage = client.createStorageManager();
final uploaded = await storage.uploadImage(
  at: Uri.file('/path/to/reference.jpg'),
);
final referenceImageURL = uploaded.url.toString();

See the XLab realtime example for external capture, recording, touch interaction, and quality controls. Detailed contracts are documented in the realtime API and storage API.

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 app-owned external video sources, including decoded video and optional PCM audio.

Dependencies

• Agora RTC SDK enables low-latency, real-time audio and video communication.
• Tencent Cloud COS SDK handles media upload and download via object storage.

Contact us

For bug reports and feature requests, please open a GitHub Issue. For integration assistance and technical support, contact us at [e-mail].

License

XmaxSDK is available under the terms of the MIT License.