Files
replicate.maui/API_Reference.md
2025-12-10 21:59:12 -05:00

30 KiB

MarketAlly.Replicate.Maui - API Reference

Complete API documentation for the MarketAlly.Replicate.Maui library.

Table of Contents


Namespaces

Namespace Description Available In
MarketAlly.Replicate.Maui Core API classes, interfaces, settings, and presets net9.0, MAUI
MarketAlly.Replicate.Maui.Controls MAUI UI controls and button configuration MAUI only
MarketAlly.Replicate.Maui.Services File save service MAUI only
MarketAlly.Replicate.Maui.ViewModels MVVM view models MAUI only
MarketAlly.Replicate.Maui.Localization Localization support MAUI only

Core API Classes

IReplicateTransformer

Interface for Replicate API image and video transformations.

public interface IReplicateTransformer

Events

Event Type Description
PredictionCreated EventHandler<PredictionCreatedEventArgs> Raised immediately when a prediction is created (before polling starts)

Methods

Image Transformation
Task<PredictionResult> TransformToAnimeAsync(
    byte[] imageBytes,
    string? customPrompt = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Transform an image to anime style using raw bytes.

Task<PredictionResult> TransformToAnimeFromBase64Async(
    string base64Image,
    string? customPrompt = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Transform an image to anime style using base64 encoded string.

Task<PredictionResult> TransformToAnimeFromUrlAsync(
    string imageUrl,
    string? customPrompt = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Transform an image to anime style from a URL.

Video Generation
Task<PredictionResult> TransformToVideoAsync(
    byte[] imageBytes,
    string? customPrompt = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Generate a video from an image using raw bytes.

Task<PredictionResult> TransformToVideoFromBase64Async(
    string base64Image,
    string? customPrompt = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Generate a video from a base64 encoded image.

Task<PredictionResult> TransformToVideoFromUrlAsync(
    string imageUrl,
    string? customPrompt = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Generate a video from an image URL.

Model Presets
Task<PredictionResult> RunPresetAsync(
    ModelPreset preset,
    byte[] imageBytes,
    string? customPrompt = null,
    Dictionary<string, object>? customParameters = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Run a prediction using a model preset with image bytes.

Task<PredictionResult> RunPresetFromBase64Async(
    ModelPreset preset,
    string base64Image,
    string? customPrompt = null,
    Dictionary<string, object>? customParameters = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Run a prediction using a model preset with base64 image.

Task<PredictionResult> RunPresetFromUrlAsync(
    ModelPreset preset,
    string imageUrl,
    string? customPrompt = null,
    Dictionary<string, object>? customParameters = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Run a prediction using a model preset with image URL.

Task<PredictionResult> RunPresetTextOnlyAsync(
    ModelPreset preset,
    string prompt,
    Dictionary<string, object>? customParameters = null,
    PredictionOptions? options = null,
    CancellationToken cancellationToken = default);

Run a text-only prediction using a model preset (no image input).

Prediction Management
Task CancelPredictionAsync(
    string predictionId,
    CancellationToken cancellationToken = default);

Cancel a running prediction.

Task<PredictionResult> GetPredictionAsync(
    string predictionId,
    CancellationToken cancellationToken = default);

Get the status of a prediction.


ReplicateTransformer

Default implementation of IReplicateTransformer.

public class ReplicateTransformer : IReplicateTransformer

Constructor

public ReplicateTransformer(
    HttpClient httpClient,
    IOptions<ReplicateSettings> settings,
    ILogger<ReplicateTransformer>? logger = null)
Parameter Type Description
httpClient HttpClient HTTP client for API requests
settings IOptions<ReplicateSettings> Configuration settings
logger ILogger<ReplicateTransformer>? Optional logger

IReplicateTransformerFactory

Factory for creating IReplicateTransformer instances with custom API tokens. Useful for BYOK (Bring Your Own Key) scenarios.

public interface IReplicateTransformerFactory

Methods

IReplicateTransformer Create();

Creates a transformer using the default configured settings.

IReplicateTransformer CreateWithToken(string apiToken);

Creates a transformer with a custom API token.

IReplicateTransformer CreateWithSettings(Action<ReplicateSettings> configure);

Creates a transformer with fully custom settings.


ReplicateSettings

Configuration settings for the Replicate API.

public class ReplicateSettings

Properties

Property Type Default Description
ApiToken string "" Replicate API token
ApiUrl string "https://api.replicate.com/v1/predictions" API endpoint URL
AuthScheme string "Token" Authentication scheme ("Bearer" or "Token")
ModelVersion string "" Default model version for image transformation
ModelName string "" Default model name
TimeoutSeconds int 300 Timeout for image predictions
PollingDelayMs int 1500 Delay between status polls
ImagePrompt string "anime style portrait..." Default image transformation prompt
VideoModelName string "" Default video model name
VideoModelVersion string "" Default video model version
VideoPrompt string "animate and loop..." Default video generation prompt
VideoTimeoutSeconds int 600 Timeout for video predictions
VideoPollingDelayMs int 3000 Polling delay for video predictions
DefaultSettings ImageTransformSettings new() Default image transform parameters
VideoSettings VideoTransformSettings new() Default video transform parameters

ImageTransformSettings

public class ImageTransformSettings
{
    public int Seed { get; set; } = 42;
    public double GuidanceScale { get; set; } = 9;
    public double Strength { get; set; } = 0.8;
    public int NumInferenceSteps { get; set; } = 30;
}

VideoTransformSettings

public class VideoTransformSettings
{
    public int? Seed { get; set; }
    public int Duration { get; set; } = 5;
    public string Size { get; set; } = "1280*720";
    public string? AudioUrl { get; set; }
    public string? NegativePrompt { get; set; }
    public bool EnablePromptExpansion { get; set; } = true;
}

Model Presets

ModelPresets (Static Class)

Predefined model presets for popular Replicate models.

public static class ModelPresets

Image Model Properties

Property Model Description
HiDreamE1 prunaai/hidream-e1.1 Fast high-quality image generation/editing
StableDiffusionXL stability-ai/sdxl Popular open-source image generation
IdeogramV3Turbo ideogram-ai/ideogram-v3-turbo Best for images with realistic text
RecraftV3Svg recraft-ai/recraft-v3-svg High-quality SVG images, logos, icons

Video Model Properties

Property Model Description
GoogleVeo3Fast google/veo-3-fast State-of-the-art video generation
Kling25TurboPro kwaivgi/kling-v2.5-turbo-pro Latest high-quality video
Kling16Pro kwaivgi/kling-v1.6-pro Professional video generation
SeedancePro bytedance/seedance-1-pro High-quality image-to-video
LumaRayFlash luma/ray-flash-2-720p Fast video with camera control
Wan21 alibaba/wan-2.1-i2v-480p Image-to-video 480p/720p
MiniMaxVideo minimax/video-01 Text and image to video

Collection Properties

public static IReadOnlyList<ModelPreset> All { get; }
public static IReadOnlyList<ModelPreset> ImageModels { get; }
public static IReadOnlyList<ModelPreset> VideoModels { get; }

Methods

public static ModelPreset? FindByName(string modelName)

Find a preset by model name or display name.


ModelPreset

A preset configuration for a specific Replicate model.

public class ModelPreset

Properties

Property Type Description
Name string Display name for the preset
ModelName string Replicate model identifier (owner/model-name)
ModelVersion string Specific model version hash
Type ModelType Output type (Image or Video)
DefaultPrompt string Default prompt for this model
DefaultParameters Dictionary<string, object> Default API parameters
ImageInputKey string Key name for image input (default: "image")
PromptKey string Key name for prompt (default: "prompt")
TimeoutSeconds int Timeout in seconds
PollingDelayMs int Polling delay in milliseconds

Methods

public Dictionary<string, object> CloneParameters()

Create a copy of the default parameters.

public Dictionary<string, object> BuildInput(
    string? prompt = null,
    string? imageData = null,
    Dictionary<string, object>? customParameters = null)

Build the input dictionary for an API call.


ModelType

public enum ModelType
{
    Image,
    Video
}

Prediction Classes

PredictionResult

Result of a prediction.

public class PredictionResult

Properties

Property Type Description
Id string Unique prediction identifier
Status string Status string: starting, processing, succeeded, failed, canceled
StatusEnum PredictionStatus Strongly-typed status enum
Output string? Output URL if succeeded
Outputs string[]? All output URLs if multiple outputs
Error string? Error message if failed
Metrics PredictionMetrics? Performance metrics
CreatedAt DateTimeOffset? When the prediction was created
StartedAt DateTimeOffset? When processing started
CompletedAt DateTimeOffset? When the prediction completed
CancelUrl string? URL to cancel the prediction

Computed Properties

Property Type Description
IsCompleted bool Whether completed (succeeded, failed, or canceled)
IsSucceeded bool Whether succeeded
IsPending bool Whether pending (starting or processing)
IsFailed bool Whether failed
IsCanceled bool Whether canceled

PredictionOptions

Options for creating a prediction.

public class PredictionOptions

Properties

Property Type Description
WebhookUrl string? Webhook URL to receive prediction updates
WebhookEventsFilter string[]? Filter events: "start", "output", "logs", "completed"
SyncModeWaitSeconds int? Sync mode wait time (1-60 seconds), null for async
WebhookOnly bool If true with sync mode, don't poll - return immediately

PredictionStatus

public enum PredictionStatus
{
    Starting,    // Prediction is starting up
    Processing,  // Prediction is actively processing
    Succeeded,   // Prediction completed successfully
    Failed,      // Prediction failed with an error
    Canceled,    // Prediction was canceled
    Unknown      // Unknown or unrecognized status
}

Extension Methods

public static PredictionStatus ToPredictionStatus(this string? status)
public static string ToApiString(this PredictionStatus status)
public static bool IsCompleted(this PredictionStatus status)
public static bool IsPending(this PredictionStatus status)

PredictionMetrics

public class PredictionMetrics
{
    public double? PredictTime { get; set; }  // Time running the model (seconds)
    public double? TotalTime { get; set; }    // Total time including queue (seconds)
}

Prediction Tracking

IPredictionTracker

Interface for tracking prediction history and monitoring pending predictions.

public interface IPredictionTracker : IDisposable

Properties

Property Type Description
PollingIntervalMs int Interval between status checks (default: 3000)
MaxHistorySize int Maximum predictions to keep (default: 50)
History IReadOnlyList<TrackedPrediction> All tracked predictions (newest first)
PendingPredictions IReadOnlyList<TrackedPrediction> Pending predictions only

Events

Event Type Description
PredictionStatusChanged EventHandler<PredictionStatusChangedEventArgs> Status changed
PredictionCompleted EventHandler<PredictionCompletedEventArgs> Prediction completed

Methods

TrackedPrediction Track(PredictionResult result, TransformationType type, byte[]? sourceImageBytes = null)
TrackedPrediction? Get(string predictionId)
Task<TrackedPrediction?> RefreshAsync(string predictionId, CancellationToken cancellationToken = default)
void ClearCompleted()
void ClearAll()

TrackedPrediction

A tracked prediction with history information.

public class TrackedPrediction

Properties

Property Type Description
Id string Prediction ID
Type TransformationType Image or Video
Status string Current status string
StatusEnum PredictionStatus Strongly-typed status
Output string? Output URL
Outputs string[]? All output URLs
Error string? Error message
Metrics PredictionMetrics? Performance metrics
CreatedAt DateTimeOffset Creation time
StartedAt DateTimeOffset? Start time
CompletedAt DateTimeOffset? Completion time
LastCheckedAt DateTimeOffset? Last status check
SourceImageBytes byte[]? Source image if stored
Elapsed TimeSpan Time since creation

MAUI Controls

ReplicateTransformerView

The main UI control for image/video transformation.

public partial class ReplicateTransformerView : ContentView

Bindable Properties

Property Type Default Description
LayoutMode TransformerLayoutMode ButtonsBelow Layout mode for the control
OverlayButtonPosition OverlayButtonPosition Bottom Position of overlay buttons
UseLocalization bool false Enable localized strings
ProcessingMessage string "Transforming..." Message during processing
ProcessingSubMessage string "This may take..." Sub-message during processing
PlaceholderText string "Select or capture..." Placeholder text
ShowCaptureButton bool true Show camera capture button
ShowPickButton bool true Show image picker button
ShowVideoButtons bool false Show video-related buttons
ButtonConfigs TransformerButtonConfigs new() Button configurations
ImagePreset ModelPreset? null Current image model preset
VideoPreset ModelPreset? null Current video model preset
CustomImagePrompt string? null Custom image prompt override
CustomVideoPrompt string? null Custom video prompt override

Read-Only Properties

Property Type Description
CurrentState TransformerState Current control state
IsProcessing bool Whether transformation is in progress
HasSourceImage bool Whether source image is set
HasResult bool Whether result is available
SourceImageBytes byte[]? Current source image bytes
ResultUrl string? URL of the transformation result
VideoUrl string? URL of video result
PredictionTracker IPredictionTracker? Internal prediction tracker

Events

Event Type
ImageSelected EventHandler<ImageSelectedEventArgs>
TransformationStarted EventHandler<TransformationStartedEventArgs>
TransformationCompleted EventHandler<TransformationCompletedEventArgs>
TransformationError EventHandler<TransformationErrorEventArgs>
PredictionTracked EventHandler<PredictionStatusChangedEventArgs>
PredictionCompleted EventHandler<PredictionCompletedEventArgs>
FileSaved EventHandler<FileSavedEventArgs>
FileSaveError EventHandler<FileSaveErrorEventArgs>
StateChanged EventHandler<StateChangedEventArgs>
ImageTapped EventHandler<ImageTappedEventArgs>

Methods

void Initialize(IReplicateTransformer transformer)
void Initialize(IReplicateTransformerFactory factory)
void ConfigureSettings(Action<ReplicateSettings> configure)
void SetImagePreset(ModelPreset preset, Dictionary<string, object>? customParameters = null)
void SetVideoPreset(ModelPreset preset, Dictionary<string, object>? customParameters = null)
Task SetImageAsync(byte[] imageBytes)
Task SetImageAsync(Stream imageStream)
Task TransformImageAsync()
Task TransformVideoAsync()
Task CancelTransformationAsync()
void Reset()
void ClearResult()
void RefreshLocalization()

TransformerLayoutMode

public enum TransformerLayoutMode
{
    ImageOnly,      // Image only, no buttons
    ButtonsBelow,   // Buttons below the image (default)
    ButtonsOverlay, // Buttons overlaid on the image
    SideBySide      // Source and result side by side
}

TransformerState

public enum TransformerState
{
    Empty,         // No image selected
    ImageSelected, // Source image is displayed
    Processing,    // Transformation in progress
    ImageResult,   // Image transformation completed
    VideoResult,   // Video transformation completed
    PlayingVideo,  // Video player is active
    Error          // Error occurred
}

Extension Methods

public static bool HasResult(this TransformerState state)
public static bool IsBusy(this TransformerState state)
public static bool CanTransform(this TransformerState state)
public static bool CanSelectImage(this TransformerState state)

Button Configuration

ButtonConfig

Configuration for a single button's appearance.

public class ButtonConfig : BindableObject

Properties

Property Type Description
Text string Button text label
IconText string Unicode/emoji icon (e.g., "📸")
ImageSource ImageSource? Image icon (takes precedence over IconText)
DisplayMode ButtonDisplayMode? Override display mode
BackgroundColor Color? Button background color
TextColor Color Button text color
IsVisible bool Whether button is visible

Events

Event Description
ConfigurationChanged Raised when any property changes

Methods

string GetDisplayText(ButtonDisplayMode defaultMode = ButtonDisplayMode.Both)
bool ShouldShowImage(ButtonDisplayMode defaultMode = ButtonDisplayMode.Both)
ImageSource? GetEffectiveImageSource(ButtonDisplayMode defaultMode = ButtonDisplayMode.Both)
void ApplyTo(Button button, ButtonDisplayMode defaultMode = ButtonDisplayMode.Both)
ButtonConfig Clone()
static ButtonConfig Create(string text, string iconText, ImageSource? imageSource = null, ButtonDisplayMode? displayMode = null)

TransformerButtonConfigs

Container for all transformer button configurations.

public class TransformerButtonConfigs : BindableObject

Properties

Property Type Description
DefaultDisplayMode ButtonDisplayMode Default mode for all buttons
OverlaySelect ButtonConfig Overlay select button
OverlayTransform ButtonConfig Overlay transform button
SideBySideCapture ButtonConfig Side-by-side capture button
SideBySidePick ButtonConfig Side-by-side pick button
SideBySideTransform ButtonConfig Side-by-side transform button
SideBySideClear ButtonConfig Side-by-side clear button
SideBySideRedo ButtonConfig Side-by-side redo button

Methods

void ApplyConfig(ButtonConfig config, Button button)
static TransformerButtonConfigs CreateDefault()

ButtonDisplayMode

public enum ButtonDisplayMode
{
    Label,  // Show only text
    Icon,   // Show only icon
    Both    // Show both icon and text
}

OverlayButtonPosition

public enum OverlayButtonPosition
{
    Top,    // Buttons at top of image
    Bottom  // Buttons at bottom of image (default)
}

Localization

ReplicateStrings

Provides localized strings for controls.

public static class ReplicateStrings

Properties

public static string CurrentCulture { get; set; }
public static IEnumerable<string> SupportedCultures { get; }

Methods

public static string Get(string key)
public static string Get(string key, string culture)
public static void SetCulture(CultureInfo culture)
public static void UseSystemCulture()
public static void RegisterTranslations(string culture, Dictionary<string, string> translations)
public static void RegisterTranslation(string culture, string key, string value)
public static bool HasCulture(string culture)
public static void ResetToDefaults()

Keys (ReplicateStrings.Keys)

Key English Value
Take "Take"
Pick "Pick"
Select "Select"
Transform "Transform"
Clear "Clear"
Redo "Redo"
Reset "Reset"
Cancel "Cancel"
Image "Image"
GenerateVideo "Generate Video"
Transforming "Transforming..."
GeneratingVideo "Generating video..."
Processing "Processing"
PleaseWait "Please wait"
TransformationComplete "Transformation complete"
TapToSelectImage "Tap to select image"
SourceImage "Source"
Result "Result"
Error "Error"
Dismiss "Dismiss"
Starting "Starting"
Succeeded "Succeeded"
Failed "Failed"
Canceled "Canceled"
Pending "Pending"

Supported Cultures

  • English (en)
  • Spanish (es)
  • French (fr)
  • German (de)
  • Chinese (zh)
  • Japanese (ja)
  • Portuguese (pt)
  • Italian (it)

Events

Event Args Classes

PredictionCreatedEventArgs

public class PredictionCreatedEventArgs : EventArgs
{
    public PredictionResult Prediction { get; }
}

TransformationStartedEventArgs

public class TransformationStartedEventArgs : EventArgs
{
    public TransformationType Type { get; }
}

TransformationCompletedEventArgs

public class TransformationCompletedEventArgs : EventArgs
{
    public TransformationType Type { get; }
    public string? ResultUrl { get; }
    public PredictionResult Result { get; }
}

TransformationErrorEventArgs

public class TransformationErrorEventArgs : EventArgs
{
    public TransformationType Type { get; }
    public Exception Error { get; }
}

ImageSelectedEventArgs

public class ImageSelectedEventArgs : EventArgs
{
    public byte[] ImageBytes { get; }
}

ImageTappedEventArgs

public class ImageTappedEventArgs : EventArgs
{
    public bool IsSourceImage { get; }
    public string? ResultUrl { get; }
    public byte[]? ImageBytes { get; }
}

FileSavedEventArgs

public class FileSavedEventArgs : EventArgs
{
    public string FilePath { get; }
    public TransformationType Type { get; }
    public long FileSizeBytes { get; }
}

FileSaveErrorEventArgs

public class FileSaveErrorEventArgs : EventArgs
{
    public TransformationType Type { get; }
    public Exception Error { get; }
}

StateChangedEventArgs

public class StateChangedEventArgs : EventArgs
{
    public TransformerState PreviousState { get; }
    public TransformerState NewState { get; }
}

PredictionStatusChangedEventArgs

public class PredictionStatusChangedEventArgs : EventArgs
{
    public TrackedPrediction Prediction { get; }
    public string PreviousStatus { get; }
    public string NewStatus { get; }
    public PredictionStatus PreviousStatusEnum { get; }
    public PredictionStatus NewStatusEnum { get; }
}

PredictionCompletedEventArgs

public class PredictionCompletedEventArgs : EventArgs
{
    public TrackedPrediction Prediction { get; }
    public bool Succeeded { get; }
    public bool Failed { get; }
    public bool Canceled { get; }
}

Exceptions

ReplicateApiException

Thrown when the Replicate API returns an error.

public class ReplicateApiException : Exception
{
    public HttpStatusCode StatusCode { get; }
    public string ResponseBody { get; }
}

ReplicateTransformationException

Thrown when a transformation fails.

public class ReplicateTransformationException : Exception
{
    public ReplicateTransformationException(string message)
    public ReplicateTransformationException(string message, Exception innerException)
}

Extension Methods

ServiceCollectionExtensions

public static IServiceCollection AddReplicateTransformer(
    this IServiceCollection services,
    Action<ReplicateSettings> configure)

public static IServiceCollection AddReplicateTransformer(
    this IServiceCollection services,
    ReplicateSettings settings)

MauiAppBuilderExtensions

public static MauiAppBuilder UseReplicateMaui(this MauiAppBuilder builder)

public static MauiAppBuilder UseReplicateMaui(
    this MauiAppBuilder builder,
    Action<ReplicateSettings> configure)

public static MauiAppBuilder UseReplicateMaui(
    this MauiAppBuilder builder,
    ReplicateSettings settings)

LocalizationExtensions

public static string Localized(this string key)
public static string Localized(this string key, string culture)

TransformationType

public enum TransformationType
{
    Image,
    Video
}

Complete Example

using MarketAlly.Replicate.Maui;
using MarketAlly.Replicate.Maui.Controls;
using MarketAlly.Replicate.Maui.Localization;

public partial class MainPage : ContentPage
{
    private readonly IReplicateTransformerFactory _factory;

    public MainPage(IReplicateTransformerFactory factory)
    {
        InitializeComponent();
        _factory = factory;

        // Initialize control
        TransformerView.Initialize(_factory);

        // Configure appearance
        TransformerView.LayoutMode = TransformerLayoutMode.SideBySide;
        TransformerView.UseLocalization = true;
        ReplicateStrings.CurrentCulture = "en";

        // Set model presets
        TransformerView.SetImagePreset(ModelPresets.HiDreamE1, new Dictionary<string, object>
        {
            { "speed_mode", "Juiced 🔥 (more speed)" }
        });

        TransformerView.SetVideoPreset(ModelPresets.GoogleVeo3Fast, new Dictionary<string, object>
        {
            { "duration", 8 }
        });

        // Subscribe to events
        TransformerView.TransformationCompleted += OnCompleted;
        TransformerView.TransformationError += OnError;
        TransformerView.PredictionTracked += OnStatusChanged;
    }

    private void OnCompleted(object? sender, TransformationCompletedEventArgs e)
    {
        Console.WriteLine($"Completed: {e.Result.Output}");
        Console.WriteLine($"Predict time: {e.Result.Metrics?.PredictTime}s");
    }

    private void OnError(object? sender, TransformationErrorEventArgs e)
    {
        DisplayAlert("Error", e.Error.Message, "OK");
    }

    private void OnStatusChanged(object? sender, PredictionStatusChangedEventArgs e)
    {
        Console.WriteLine($"Status: {e.NewStatusEnum}");
    }
}

This API Reference is for MarketAlly.Replicate.Maui version 1.5.0