PICSART CREATIVE APIS

Description

This is a Java SDK of Picsart Programmable Image APIs and Picsart GenAI APIs. You can easily do many actions with your images just by adding few lines of code to your Java or Kotlin projects.

Installation

To use the SDK, add the following dependency to your Maven pom.xml file:

<dependency>
    <groupId>com.picsart</groupId>
    <artifactId>picsart-creative-apis-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

If you are using Gradle, add the following to your build.gradle file:

implementation 'com.picsart:picsart-creative-apis-java-sdk:1.0.0'

Warning: The SDK is using Reactor java and has a transitive dependency on io.projectreactor:reactor-core. If you are using a different version of Reactor, you may face compatibility issues. In this case, you can exclude the transitive dependency and add your own version of Reactor to your project.

Usage

Get an API instance

import com.picsart.creativeapis.PicsartEnterprise;
import com.picsart.creativeapis.image.ImageApi;
import com.picsart.creativeapis.genai.GenAIApi;

// Get an instance of Image API with default baseUrl and timeout
ImageApi imageApi = PicsartEnterprise.createImageApi("YOUR_API_KEY");

// Get an instance of Image API with custom baseUrl and timeout
ImageApi customBaseUrlImageApi = PicsartEnterprise.createImageApi("YOUR_API_KEY")
                        .withBaseUrl("https://custom-base-url.com")
                        .withTimeout(Duration.ofSeconds(10));

// Get an instance of GenAI API
GenAIApi genaiApi = PicsartEnterprise.createGenAIApi("YOUR_API_KEY");

// Get an instance of GenAI API with custom baseUrl and timeout
GenAIApi customBaseUrlGenaiApi = PicsartEnterprise.createGenAIApi("YOUR_API_KEY")
                        .withBaseUrl("https://custom-base-url.com")
                        .withTimeout(Duration.ofSeconds(10));

Create an ImageSource instance

import com.picsart.busobj.image.ImageSource;
import com.picsart.creativeapis.image.ImageApi;
import com.picsart.creativeapis.image.models.ImageSource;

import java.io.File;

var imageUrl = ImageSource.fromUrl("https://url-to-your-image.jpg");
// or
var imageFile = ImageSource.fromFile(new File("path/to/your-image.jpg"));
// or
var imageId = ImageSource.fromImageId("your-image-id");

Remove background

RemoveBackgroundParameters parameters = RemoveBackgroundParameters.builder(mainImageSource)
        .bgImage(backgroundImageSource)
        .build();
Mono<RemoveBackgroundResult> removeBackgroundResultMono = imageApi.removeBackground(parameters);
removeBackgroundResultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check RemoveBackgroundExample.java.

Adjust image

AdjustParameters parameters = AdjustParameters.builder(imageSource)
                .brightness(20)
                .contrast(30)
                .saturation(40)
                .build();
Mono<AdjustResult> adjustResultMono = imageApi.adjust(parameters);
adjustResultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check AdjustExample.java.

Apply effect

EffectParameters parameters = EffectParameters.builder(imageSource, effectName)
        .build();
Mono<EffectResult> resultMono = imageApi.effect(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check EffectExample.java.

Get list of effects

Mono<ListEffectsResult> resultMono = imageApi.listEffects();
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Effects: " + result.effects());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check ListEffectsExample.java.

//Effects Previews

Preview selected effects on an image

EffectsPreviewsParameters parameters = EffectsPreviewsParameters.builder(imageSource)
                .addEffectName(effectName1)
                .addEffectName(effectName2)
                .addEffectName(effectName3)
                .format(ImageFormat.PNG)
                .build();
Mono<EffectsPreviewsResult> resultMono = imageApi.effectsPreviews(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result images with effects" + result.effectsPreviews());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check EffectsPreviewsExample.java.

Upload Image

Mono<UploadResult> resultMono = imageApi.upload(imageFile); // either imageFile or imageUrl
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check UploadExample.java.

Upscale

 UpscaleParameters parameters = UpscaleParameters.builder(imageSource)
        .upscaleFactor(4)
        .format(ImageFormat.PNG)
        .build();
Mono<UpscaleResult> resultMono = imageApi.upscale(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check UpscaleExample.java.

Ultra Upscale

UltraUpscaleParameters parameters = UltraUpscaleParameters.builder(imageSource)
        .mode(UpscaleMode.ASYNC)
        .upscaleFactor(4)
        .format(ImageFormat.PNG)
        .build();
Mono<UltraUpscaleResult> resultMono = imageApi.ultraUpscale(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check UltraUpscaleExample.java.

Ultra Enhance

UltraEnhanceParameters parameters = UltraEnhanceParameters.builder(imageSource)
        .upscaleFactor(4)
        .format(ImageFormat.PNG)
        .build();
Mono<UltraEnhanceResult> resultMono = imageApi.ultraEnhance(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check UltraEnhanceExample.java.

Enhance face

EnhanceFaceParameters parameters = EnhanceFaceParameters.builder(imageSource)
                .format(ImageFormat.PNG)
                .build();
Mono<EnhanceFaceResult> resultMono = imageApi.enhanceFace(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check EnhanceFaceExample.java.

Surface Map

SurfaceMapParameters parameters = SurfaceMapParameters.builder(mainImageSource, maskSource, stickerSource)
                .format(ImageFormat.PNG)
                .build();
Mono<SurfaceMapResult> resultMono = imageApi.surfaceMap(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check SurfaceMapExample.java.

Generate background textures

BackgroundTextureParameters parameters = BackgroundTextureParameters.builder(imageSource)
                .format(ImageFormat.PNG)
                .width(800)
                .height(800)
                .pattern(BackgroundTexturePattern.DIAMOND)
                .build();
        Mono<BackgroundTextureResult> resultMono = imageApi.backgroundTexture(parameters);
        resultMono
                .subscribe(result -> { // non-blocking subscribe
                    System.out.println("Result Image: " + result.image());
                    System.out.println("Result metadata: " + result.metadata());
                });

For more details please check BackgroundTextureExample.java.

Get balance

Mono<BalanceResult> resultMono = imageApi.balance();
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result credits: " + result.credits());
        });

For more details please check BalanceExample.java.

Generate images from text with GenAI

Text2ImageParameters parameters = Text2ImageParameters.builder("your-prompt", "your-negative-prompt")
        .count(1)
        .width(512)
        .height(512)
        .build();
Mono<Text2ImageResult> resultMono = genAIApi.text2Image(parameters);
resultMono
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result Images: " + result.images());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check Text2ImageExample.java.

Apply multiple modifications

In the example below we are generating an image from text, then removing the background from the generated image, and finally upscaling the result.

Text2ImageParameters parameters = Text2ImageParameters.builder("your-prompt", "your-negative-prompt")
        .count(10)
        .width(512)
        .height(512)
        .build();
Mono<Text2ImageResult> resultMono = genAIApi.text2Image(parameters);
resultMono
        .flatMapIterable(Text2ImageResult::images) // flatMapIterable is used to iterate over the result images and process each of them individually
        .flatMap(image -> { // this will be called for each image in the result (10 times in this case)
            RemoveBackgroundParameters removeBackgroundParameters = RemoveBackgroundParameters
                    .builder(image.toImageSource())
                    .build();
            return imageApi.removeBackground(removeBackgroundParameters); // remove background from each image
        })
        .flatMap(removeBackgroundResult -> { // this will be called for each image in the result (10 times in this case)
            var imageSource = removeBackgroundResult.image().toImageSource();
            UpscaleParameters upscaleParameters = UpscaleParameters.builder(imageSource)
                     .upscaleFactor(2)
                     .build();
            return imageApi.upscale(upscaleParameters); // upscale each image
        })
        .subscribe(result -> { // non-blocking subscribe
            // each image will be printed separately
            System.out.println("Result Image: " + result.image());
            System.out.println("Result metadata: " + result.metadata());
        });

For more details please check Text2ImageRemoveBackgroundUpscaleExample.java.

Error handling and retries

Api exceptions are handled by the SDK and are thrown as ApiException or child of it. If the response status is other than 2xx, FailureResponseException or child of it is thrown according to the response status code. Exceptions that can potentially be resolved by retrying the request like ServiceUnavailableException are marked with Recoverable interface. You can catch those exceptions and retry the request if needed.

Example of retrying a request in case of a recoverable exception:

Mono<BalanceResult> resultMono = imageApi.balance();
resultMono
        // can be used to perform a side-effect in case of an error
        .doOnError(throwable -> {
            System.out.println("exception: " + throwable.getMessage());
        })
        // Retry 3 times with an initial backoff of 2 seconds. 
        // The delay between retries will increase exponentially up to max delay of 5 seconds.
        .retryWhen(Retry.backoff(3, Duration.ofSeconds(2))
                .maxBackoff(Duration.ofSeconds(5))
                 .filter(throwable -> throwable instanceof Recoverable)
                .onRetryExhaustedThrow((retryBackoffSpec, retrySignal) -> new RuntimeException("Retry exhausted", retrySignal.failure()))
        )
        .subscribe(result -> { // non-blocking subscribe
            System.out.println("Result credits: " + result.credits());
        });

License

Picsart Creative APIs SDK is provided under the MIT license that can be found in the LICENSE file. By using, distributing, or contributing to this project, you agree to the terms and conditions of this license.

This project has some third-party dependencies, each of which may have independent licensing:

• Jackson Databind:2.17.1 (The Apache Software License, Version 2.0)
• Guava:33.2.1-jre (The Apache Software License, Version 2.0)
• Reactor Netty HTTP:1.1.19 (The Apache Software License, Version 2.0)
• Reactor Core:3.6.6 (The Apache Software License, Version 2.0)
• Jakarta Validation API:3.1.0 (The Apache Software License, Version 2.0)
• Apache BVal JSR:3.0.0 (The Apache Software License, Version 2.0)
• Apache Tika Core:2.9.2 (The Apache Software License, Version 2.0)
• MapStruct:1.5.5.Final (The Apache Software License, Version 2.0)
• SLF4J API:2.0.13 (MIT License)
• SLF4J Simple:2.0.13 (MIT License)

How to contribute?

If you like Picsart Creative APIs SDK and would like to contribute to this open-source project, please check the Contribution guide.