picsart creative apis java sdk

Picsart 크리에이티브 API

설명

이는 Picsart 프로그래밍 가능 이미지 API 및 Picsart GenAI API의 Java SDK입니다. Java 또는 Kotlin 프로젝트에 코드 몇 줄만 추가하면 이미지로 다양한 작업을 쉽게 수행할 수 있습니다.

설치

SDK를 사용하려면 Maven pom.xml 파일에 다음 종속성을 추가하세요.

< dependency >
    < groupId >com.picsartgroupId >
    < artifactId >picsart-creative-apis-java-sdkartifactId >
    < version >1.0.0version >
dependency >

Gradle을 사용하는 경우 build.gradle 파일에 다음을 추가하세요.

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

경고 : SDK는 Reactor java를 사용하고 있으며 io.projectreactor:reactor-core 에 대한 전이적 종속성을 갖습니다. 다른 버전의 Reactor를 사용하는 경우 호환성 문제가 발생할 수 있습니다. 이 경우 전이적 종속성을 제외하고 자신의 Reactor 버전을 프로젝트에 추가할 수 있습니다.

용법

API 인스턴스 가져오기

 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 ));

ImageSource 인스턴스 만들기

 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" );

배경 제거

 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 ());
        });

자세한 내용은 RemoveBackgroundExample.java를 확인하세요.

이미지 조정

 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 ());
        });

자세한 내용은 adjustExample.java를 확인하세요.

효과 적용

 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 ());
        });

자세한 내용은 EffectExample.java를 확인하세요.

효과 목록 가져오기

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

자세한 내용은 ListEffectsExample.java를 확인하세요.

//효과 미리보기

이미지에서 선택한 효과 미리보기

 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 ());
        });

자세한 내용은 EffectsPreviewsExample.java를 확인하세요.

이미지 업로드

 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 ());
        });

자세한 내용은 UploadExample.java를 확인하세요.

고급

 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 ());
        });

자세한 내용은 UpscaleExample.java를 확인하세요.

울트라 업스케일

 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 ());
        });

자세한 내용은 UltraUpscaleExample.java를 확인하세요.

울트라 강화

 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 ());
        });

자세한 내용은 UltraEnhanceExample.java를 확인하세요.

얼굴 강화

 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 ());
        });

자세한 내용은 EnhanceFaceExample.java를 확인하세요.

표면 지도

 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 ());
        });

자세한 내용은 SurfaceMapExample.java를 확인하세요.

배경 텍스처 생성

 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 ());
                });

자세한 내용은 BackgroundTextureExample.java를 확인하세요.

잔액 확보

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

자세한 내용은 BalanceExample.java를 확인하세요.

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 ());
        });

자세한 내용은 Text2ImageExample.java를 확인하세요.

여러 수정사항 적용

아래 예에서는 텍스트에서 이미지를 생성한 다음 생성된 이미지에서 배경을 제거하고 마지막으로 결과의 크기를 확대합니다.

 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 ());
        });

자세한 내용은 Text2ImageRemoveBackgroundUpscaleExample.java를 확인하세요.

오류 처리 및 재시도

Api 예외는 SDK에 의해 처리되며 ApiException 또는 그 하위 항목으로 발생합니다. 응답 상태가 2xx가 아닌 경우 응답 상태 코드에 따라 FailureResponseException 또는 그 하위가 발생합니다. ServiceUnavailableException 과 같은 요청을 재시도하여 잠재적으로 해결될 수 있는 예외는 Recoverable 인터페이스로 표시됩니다. 이러한 예외를 포착하고 필요한 경우 요청을 다시 시도할 수 있습니다.

복구 가능한 예외가 발생한 경우 요청을 재시도하는 예:

 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 ());
        });

특허

Picsart Creative API SDK는 LICENSE 파일에 있는 MIT 라이선스에 따라 제공됩니다. 이 프로젝트를 사용, 배포 또는 기여함으로써 귀하는 본 라이센스의 이용 약관에 동의하게 됩니다.

이 프로젝트에는 일부 타사 종속성이 있으며 각 종속성은 독립적인 라이선스를 가질 수 있습니다.

• Jackson Databind:2.17.1(Apache 소프트웨어 라이센스, 버전 2.0)
• Guava:33.2.1-jre(Apache 소프트웨어 라이센스, 버전 2.0)
• Reactor Netty HTTP:1.1.19(Apache 소프트웨어 라이센스, 버전 2.0)
• Reactor Core:3.6.6(Apache 소프트웨어 라이선스, 버전 2.0)
• Jakarta Validation API:3.1.0(Apache 소프트웨어 라이센스, 버전 2.0)
• Apache BVal JSR:3.0.0(Apache 소프트웨어 라이센스, 버전 2.0)
• Apache Tika Core:2.9.2(Apache 소프트웨어 라이센스, 버전 2.0)
• MapStruct:1.5.5.Final(Apache 소프트웨어 라이센스, 버전 2.0)
• SLF4J API:2.0.13 (MIT 라이센스)
• SLF4J Simple:2.0.13 (MIT 라이센스)

어떻게 기여하나요?

Picsart Creative API SDK가 마음에 들고 이 오픈 소스 프로젝트에 기여하고 싶다면 기여 가이드를 확인하세요.