{"id":24117084,"url":"https://github.com/picsart/picsart-creative-apis-java-sdk","last_synced_at":"2025-09-18T06:31:57.721Z","repository":{"id":248859466,"uuid":"821347579","full_name":"PicsArt/picsart-creative-apis-java-sdk","owner":"PicsArt","description":"Picsart Creative APIs SDK for Java. Includes helper methods and functions for Programmable Image APIs (e.g. Remove Background, Upscale, Enhance, Effects) and the GenAI APIs (e.g. Text2Image, Replace, Expand Image).","archived":false,"fork":false,"pushed_at":"2024-08-05T12:32:57.000Z","size":4355,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-04T15:19:32.348Z","etag":null,"topics":["apis","creative","effects","enhance","enhance-image","filters","genai","image","java","library","remove-image-background","removebg","sdk","text2image","upscale","upscale-image"],"latest_commit_sha":null,"homepage":"https://picsart.io","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PicsArt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-28T10:38:17.000Z","updated_at":"2024-09-04T01:23:46.000Z","dependencies_parsed_at":"2024-07-23T11:57:45.576Z","dependency_job_id":null,"html_url":"https://github.com/PicsArt/picsart-creative-apis-java-sdk","commit_stats":null,"previous_names":["picsart/picsart-creative-apis-java-sdk"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicsArt%2Fpicsart-creative-apis-java-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicsArt%2Fpicsart-creative-apis-java-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicsArt%2Fpicsart-creative-apis-java-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicsArt%2Fpicsart-creative-apis-java-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PicsArt","download_url":"https://codeload.github.com/PicsArt/picsart-creative-apis-java-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233456107,"owners_count":18678963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apis","creative","effects","enhance","enhance-image","filters","genai","image","java","library","remove-image-background","removebg","sdk","text2image","upscale","upscale-image"],"created_at":"2025-01-11T07:38:17.344Z","updated_at":"2025-09-18T06:31:52.223Z","avatar_url":"https://github.com/PicsArt.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PICSART CREATIVE APIS\n\n## Description\n\nThis is a Java SDK of Picsart Programmable Image APIs and Picsart GenAI APIs. \nYou can easily do many actions with your images just by adding few lines of code to your Java or Kotlin projects.\n\n\n## Installation\n\nTo use the SDK, add the following dependency to your Maven `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.picsart\u003c/groupId\u003e\n    \u003cartifactId\u003epicsart-creative-apis-java-sdk\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nIf you are using Gradle, add the following to your `build.gradle` file:\n\n```gradle\nimplementation 'com.picsart:picsart-creative-apis-java-sdk:1.0.0'\n```\n\n_**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.\n\n## Usage\n\n### _Get an API instance_\n\n```java\nimport com.picsart.creativeapis.PicsartEnterprise;\nimport com.picsart.creativeapis.image.ImageApi;\nimport com.picsart.creativeapis.genai.GenAIApi;\n\n// Get an instance of Image API with default baseUrl and timeout\nImageApi imageApi = PicsartEnterprise.createImageApi(\"YOUR_API_KEY\");\n\n// Get an instance of Image API with custom baseUrl and timeout\nImageApi customBaseUrlImageApi = PicsartEnterprise.createImageApi(\"YOUR_API_KEY\")\n                        .withBaseUrl(\"https://custom-base-url.com\")\n                        .withTimeout(Duration.ofSeconds(10));\n\n// Get an instance of GenAI API\nGenAIApi genaiApi = PicsartEnterprise.createGenAIApi(\"YOUR_API_KEY\");\n\n// Get an instance of GenAI API with custom baseUrl and timeout\nGenAIApi customBaseUrlGenaiApi = PicsartEnterprise.createGenAIApi(\"YOUR_API_KEY\")\n                        .withBaseUrl(\"https://custom-base-url.com\")\n                        .withTimeout(Duration.ofSeconds(10));\n```\n\n### _Create an ImageSource instance_\n\n```java\nimport com.picsart.busobj.image.ImageSource;\nimport com.picsart.creativeapis.image.ImageApi;\nimport com.picsart.creativeapis.image.models.ImageSource;\n\nimport java.io.File;\n\nvar imageUrl = ImageSource.fromUrl(\"https://url-to-your-image.jpg\");\n// or\nvar imageFile = ImageSource.fromFile(new File(\"path/to/your-image.jpg\"));\n// or\nvar imageId = ImageSource.fromImageId(\"your-image-id\");\n\n```\n\n### _Remove background_\n\n```java\nRemoveBackgroundParameters parameters = RemoveBackgroundParameters.builder(mainImageSource)\n        .bgImage(backgroundImageSource)\n        .build();\nMono\u003cRemoveBackgroundResult\u003e removeBackgroundResultMono = imageApi.removeBackground(parameters);\nremoveBackgroundResultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\nFor more details please check [RemoveBackgroundExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/RemoveBackgroundExample.java).\n\n### _Adjust image_\n\n```java\nAdjustParameters parameters = AdjustParameters.builder(imageSource)\n                .brightness(20)\n                .contrast(30)\n                .saturation(40)\n                .build();\nMono\u003cAdjustResult\u003e adjustResultMono = imageApi.adjust(parameters);\nadjustResultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n\n```\nFor more details please check [AdjustExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/AdjustExample.java).\n\n### _Apply effect_\n\n```java\nEffectParameters parameters = EffectParameters.builder(imageSource, effectName)\n        .build();\nMono\u003cEffectResult\u003e resultMono = imageApi.effect(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [EffectExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/EffectExample.java).\n\n### _Get list of effects_\n\n```java\nMono\u003cListEffectsResult\u003e resultMono = imageApi.listEffects();\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Effects: \" + result.effects());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [ListEffectsExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/ListEffectsExample.java).\n\n//Effects Previews\n### _Preview selected effects on an image_\n\n```java\nEffectsPreviewsParameters parameters = EffectsPreviewsParameters.builder(imageSource)\n                .addEffectName(effectName1)\n                .addEffectName(effectName2)\n                .addEffectName(effectName3)\n                .format(ImageFormat.PNG)\n                .build();\nMono\u003cEffectsPreviewsResult\u003e resultMono = imageApi.effectsPreviews(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result images with effects\" + result.effectsPreviews());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [EffectsPreviewsExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/EffectsPreviewsExample.java).\n\n### _Upload Image_\n\n```java\nMono\u003cUploadResult\u003e resultMono = imageApi.upload(imageFile); // either imageFile or imageUrl\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [UploadExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/UploadExample.java).\n\n### _Upscale_\n\n```java\n UpscaleParameters parameters = UpscaleParameters.builder(imageSource)\n        .upscaleFactor(4)\n        .format(ImageFormat.PNG)\n        .build();\nMono\u003cUpscaleResult\u003e resultMono = imageApi.upscale(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [UpscaleExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/UpscaleExample.java).\n\n\n### _Ultra Upscale_\n\n```java\nUltraUpscaleParameters parameters = UltraUpscaleParameters.builder(imageSource)\n        .mode(UpscaleMode.ASYNC)\n        .upscaleFactor(4)\n        .format(ImageFormat.PNG)\n        .build();\nMono\u003cUltraUpscaleResult\u003e resultMono = imageApi.ultraUpscale(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [UltraUpscaleExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/UltraUpscaleExample.java).\n\n### _Ultra Enhance_\n\n```java\nUltraEnhanceParameters parameters = UltraEnhanceParameters.builder(imageSource)\n        .upscaleFactor(4)\n        .format(ImageFormat.PNG)\n        .build();\nMono\u003cUltraEnhanceResult\u003e resultMono = imageApi.ultraEnhance(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [UltraEnhanceExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/UltraEnhanceExample.java).\n\n### _Enhance face_\n```java\nEnhanceFaceParameters parameters = EnhanceFaceParameters.builder(imageSource)\n                .format(ImageFormat.PNG)\n                .build();\nMono\u003cEnhanceFaceResult\u003e resultMono = imageApi.enhanceFace(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [EnhanceFaceExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/EnhanceFaceExample.java).\n\n### _Surface Map_\n```java\nSurfaceMapParameters parameters = SurfaceMapParameters.builder(mainImageSource, maskSource, stickerSource)\n                .format(ImageFormat.PNG)\n                .build();\nMono\u003cSurfaceMapResult\u003e resultMono = imageApi.surfaceMap(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [SurfaceMapExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/SurfaceMapExample.java).\n\n### _Generate background textures_\n```java\nBackgroundTextureParameters parameters = BackgroundTextureParameters.builder(imageSource)\n                .format(ImageFormat.PNG)\n                .width(800)\n                .height(800)\n                .pattern(BackgroundTexturePattern.DIAMOND)\n                .build();\n        Mono\u003cBackgroundTextureResult\u003e resultMono = imageApi.backgroundTexture(parameters);\n        resultMono\n                .subscribe(result -\u003e { // non-blocking subscribe\n                    System.out.println(\"Result Image: \" + result.image());\n                    System.out.println(\"Result metadata: \" + result.metadata());\n                });\n```\n\nFor more details please check [BackgroundTextureExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/BackgroundTextureExample.java).\n\n### _Get balance_\n```java\nMono\u003cBalanceResult\u003e resultMono = imageApi.balance();\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result credits: \" + result.credits());\n        });\n```\n\nFor more details please check [BalanceExample.java](src/examples/java/com/picsart/creativeapis/examples/imageapi/BalanceExample.java).\n\n### _Generate images from text with GenAI_\n\n```java\nText2ImageParameters parameters = Text2ImageParameters.builder(\"your-prompt\", \"your-negative-prompt\")\n        .count(1)\n        .width(512)\n        .height(512)\n        .build();\nMono\u003cText2ImageResult\u003e resultMono = genAIApi.text2Image(parameters);\nresultMono\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result Images: \" + result.images());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [Text2ImageExample.java](src/examples/java/com/picsart/creativeapis/examples/genai/Text2ImageExample.java).\n\n### _Apply multiple modifications_\n\nIn the example below we are generating an image from text, then removing the background from the generated image, and finally upscaling the result.\n\n```java\nText2ImageParameters parameters = Text2ImageParameters.builder(\"your-prompt\", \"your-negative-prompt\")\n        .count(10)\n        .width(512)\n        .height(512)\n        .build();\nMono\u003cText2ImageResult\u003e resultMono = genAIApi.text2Image(parameters);\nresultMono\n        .flatMapIterable(Text2ImageResult::images) // flatMapIterable is used to iterate over the result images and process each of them individually\n        .flatMap(image -\u003e { // this will be called for each image in the result (10 times in this case)\n            RemoveBackgroundParameters removeBackgroundParameters = RemoveBackgroundParameters\n                    .builder(image.toImageSource())\n                    .build();\n            return imageApi.removeBackground(removeBackgroundParameters); // remove background from each image\n        })\n        .flatMap(removeBackgroundResult -\u003e { // this will be called for each image in the result (10 times in this case)\n            var imageSource = removeBackgroundResult.image().toImageSource();\n            UpscaleParameters upscaleParameters = UpscaleParameters.builder(imageSource)\n                     .upscaleFactor(2)\n                     .build();\n            return imageApi.upscale(upscaleParameters); // upscale each image\n        })\n        .subscribe(result -\u003e { // non-blocking subscribe\n            // each image will be printed separately\n            System.out.println(\"Result Image: \" + result.image());\n            System.out.println(\"Result metadata: \" + result.metadata());\n        });\n```\n\nFor more details please check [Text2ImageRemoveBackgroundUpscaleExample.java](src/examples/java/com/picsart/creativeapis/examples/Text2ImageRemoveBackgroundUpscaleExample.java).\n\n### _Error handling and retries_\nApi exceptions are handled by the SDK and are thrown as [ApiException](src/main/java/com/picsart/creativeapis/busobj/exception/ApiException.java) or child of it. \nIf the response status is other than 2xx, `FailureResponseException` or child of it is thrown according to the response status code.\nExceptions that can potentially be resolved by retrying the request like `ServiceUnavailableException` are marked with [Recoverable interface](src/main/java/com/picsart/creativeapis/busobj/exception/Recoverable.java).\nYou can catch those exceptions and retry the request if needed.\n\nExample of retrying a request in case of a recoverable exception:\n```java\nMono\u003cBalanceResult\u003e resultMono = imageApi.balance();\nresultMono\n        // can be used to perform a side-effect in case of an error\n        .doOnError(throwable -\u003e {\n            System.out.println(\"exception: \" + throwable.getMessage());\n        })\n        // Retry 3 times with an initial backoff of 2 seconds. \n        // The delay between retries will increase exponentially up to max delay of 5 seconds.\n        .retryWhen(Retry.backoff(3, Duration.ofSeconds(2))\n                .maxBackoff(Duration.ofSeconds(5))\n                 .filter(throwable -\u003e throwable instanceof Recoverable)\n                .onRetryExhaustedThrow((retryBackoffSpec, retrySignal) -\u003e new RuntimeException(\"Retry exhausted\", retrySignal.failure()))\n        )\n        .subscribe(result -\u003e { // non-blocking subscribe\n            System.out.println(\"Result credits: \" + result.credits());\n        });\n```\n\n\n# License\n\nPicsart Creative APIs SDK is provided under the MIT license that can be found in the\n[LICENSE](./LICENSE) file.\nBy using, distributing, or contributing to this project, you agree to\nthe terms and conditions of this license.\n\nThis project has some third-party dependencies, each of which may have independent licensing:\n\n- [Jackson Databind:2.17.1](https://github.com/FasterXML/jackson) ([The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt))\n- [Guava:33.2.1-jre](https://github.com/google/guava/) ([The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt))\n- [Reactor Netty HTTP:1.1.19](https://github.com/reactor/reactor-netty) ([The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt))\n- [Reactor Core:3.6.6](https://github.com/reactor/reactor-core) ([The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt))\n- [Jakarta Validation API:3.1.0](https://www.eclipse.org) ([The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt))\n- [Apache BVal JSR:3.0.0](https://bval.apache.org/) ([The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt))\n- [Apache Tika Core:2.9.2](https://tika.apache.org/) ([The Apache Software License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt))\n- [MapStruct:1.5.5.Final](https://mapstruct.org/mapstruct/) ([The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt))\n- [SLF4J API:2.0.13](http://www.slf4j.org) ([MIT License](http://www.opensource.org/licenses/mit-license.php))\n- [SLF4J Simple:2.0.13](http://www.slf4j.org) ([MIT License](http://www.opensource.org/licenses/mit-license.php))\n\n# How to contribute?\n\nIf you like Picsart Creative APIs SDK and would like to contribute to this open-source project, please check the [Contribution\nguide](./CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpicsart%2Fpicsart-creative-apis-java-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpicsart%2Fpicsart-creative-apis-java-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpicsart%2Fpicsart-creative-apis-java-sdk/lists"}