PICSART CREATIVE APIS Python SDK

Overview

The Picsart Python SDK provides seamless access to Picsart Programmable Image APIs and Picsart GenAI APIs, enabling developers to enhance and manipulate images with minimal code. The SDK simplifies the integration of advanced image processing features, making it easy to build creative and AI-driven applications.

Requirements

Python 3.9 or higher

Getting Started

Installation

Install the SDK via pip:

pip install git+https://github.com/PicsArt/picsart-creative-apis-python-sdk 

Or if you want to install a specific version:

pip install git+https://github.com/PicsArt/[email protected]

Create a Client

Option 1: Using Default Session

If the PICSART_API_KEY environment variable is set, you can quickly create a client:

import picsart_sdk
from picsart_sdk.clients import UploadClient
from picsart_sdk import PicsartAPI

upload_client: UploadClient = picsart_sdk.client(PicsartAPI.UPLOAD)

Option 2: Passing the PICSART_API_KEY manually

You can also pass the API key directly to the API. Manually passing the API key takes precedence over using the environment variable:

import picsart_sdk
from picsart_sdk.clients import UploadClient
from picsart_sdk import PicsartAPI

upload_client: UploadClient = picsart_sdk.client(PicsartAPI.UPLOAD, api_key="YOUR-API-KEY")

NOTE: We recommend always using Python type hinting, such as upload_client: UploadClient = picsart_sdk.client(...), to fully leverage IDE autocompletion and improve code readability.

Features and Examples

1. Uploading an Image

import picsart_sdk
from picsart_sdk import PicsartAPI
from picsart_sdk.api_responses import ApiResponse
from picsart_sdk.clients import UploadClient

upload_client: UploadClient = picsart_sdk.client(PicsartAPI.UPLOAD)

response: ApiResponse = upload_client.upload_image(image_path="/path/to/image.jpg")
print(response.data.url)
response: ApiResponse = upload_client.upload_image(image_url="https://domain.com/file.jpg")
print(response.data.url)

2. Remove Background

Simple remove background using a file or from url

import picsart_sdk
from picsart_sdk import PicsartAPI
from picsart_sdk.clients import RemoveBackgroundClient
from picsart_sdk.api_responses import ApiResponse

client: RemoveBackgroundClient = picsart_sdk.client(PicsartAPI.REMOVE_BACKGROUND)

response: ApiResponse = client.remove_background(image_path="./file.jpg")
print(response.data.url)

response = client.remove_background(image_url="https://domain.com/image.jpg")
print(response.data.url)

Advanced Use Case

In case you want to apply different features available for remove background, you can pass them as parameters, having the same names.

import picsart_sdk
from picsart_sdk import PicsartAPI
from picsart_sdk.api_responses import ApiResponse
from picsart_sdk.clients import RemoveBackgroundClient

client: RemoveBackgroundClient = picsart_sdk.client(PicsartAPI.REMOVE_BACKGROUND)
response: ApiResponse = client.remove_background(image_url="https://domain.com/image.jpg", stroke_size=2, stroke_color="red")
print(response.data.url)

You can check the API Reference to find the available options for any of the supported APIs.

3. Ultra Upscale an Image

Using synchronous mode (not feasible for large images)

import picsart_sdk
from picsart_sdk import PicsartAPI
from picsart_sdk.clients import UltraUpscaleClient
from picsart_sdk.api_responses import ApiResponse
from picsart_sdk.clients.requests_models.ultra_upscale_request import UltraUpscaleMode

client: UltraUpscaleClient = picsart_sdk.client(PicsartAPI.ULTRA_UPSCALE)
response: ApiResponse = client.ultra_upscale(image_path="./your-file.jpg", mode=UltraUpscaleMode.SYNC)
print(response.data.url)

Using asynchronous mode (recommended)

import time
import picsart_sdk
from picsart_sdk import PicsartAPI
from picsart_sdk.api_responses import ApiResponse
from picsart_sdk.clients import UltraUpscaleClient
from picsart_sdk.clients.requests_models.ultra_upscale_request import UltraUpscaleMode

client: UltraUpscaleClient = picsart_sdk.client(PicsartAPI.ULTRA_UPSCALE)
response: ApiResponse = client.ultra_upscale(image_path="./your-file.jpg", mode=UltraUpscaleMode.ASYNC)
time.sleep(10)  # depending on the load of the service and the size of the image, the time to process can differ
response: ApiResponse = client.get_result(inference_id=response.inference_id)
print(response.data.url)

To find additional code snippets, explore the examples folder.

HTTP Async Client

The SDK includes an async HTTP client built on Python's async implementation, enabling non-blocking API requests for optimal performance in high-concurrency applications. The async client mirrors the interface of the synchronous client, making it easy to switch between the two.

import asyncio

import picsart_sdk
from picsart_sdk import PicsartAPI
from picsart_sdk.clients import AsyncUploadClient

async def upload_image_async():
    # Create an async client
    client: AsyncUploadClient = picsart_sdk.async_client(PicsartAPI.UPLOAD)

    # Upload an image using the async/await syntax
    response = await client.upload_image(image_path="./file.jpg")
    print(response.data.url)

asyncio.run(upload_image_async())

Asynchronous processing

Some Picsart API endpoints support asynchronous processing, allowing you to initiate a request that returns an inference_id. This enables the client to retrieve the results of the requested operation at a later time using that inference ID.

The SDK provides a convenient get_result method on the client object for fetching the final output of such operations.

Please refer to the API Documentation for details.

import time
import picsart_sdk
from picsart_sdk import PicsartAPI
from picsart_sdk.clients import UltraUpscaleClient
from picsart_sdk.clients.requests_models.ultra_upscale_request import UltraUpscaleMode

client: UltraUpscaleClient = picsart_sdk.client(PicsartAPI.ULTRA_UPSCALE)
response1 = client.ultra_upscale(image_path="./file.jpg", mode=UltraUpscaleMode.ASYNC)
print(response1)
# expect something like: ApiResponse(status='queued', data=None, inference_id='6862207a-838c-48c6-ba12-cf6083a9d76e')

time.sleep(10)
response2 = client.get_result(inference_id=response1.inference_id)
print(response2)

The response would be something like

ApiResponse(
  status='success', 
  data=ApiResponseData(
      id='702eb942-62fb-4c73-834b-db189cca923e.png', 
      url='https://cdn.picsart.io/702eb942-62fb-4c73-834b-db189cca923e.png'
  ), 
  inference_id=None
)

SDK Documentation Reference

You can access the comprehensive SDK documentation to explore detailed guides, SDK references, and usage examples.

Supported APIs

The SDK supports interactions with the following Picsart APIs

Image APIs

• Upload
• Remove Background
• Upscale
• Ultra Upscale
• Ultra Enhance
• Face Enhancement
• Effects
• Effects Previews
• AI Effects
• Color Transfer
• Style Transfer
• Masks
• Masks Previews
• Adjust
• Basic Edit
• Texture Generator
• Vectorizer
• Surfacemap Image
• Image Tagging
• Image Description
• Balance

GenAI

• Text2Image
• Text2Text
• Inpainting
• Outpainting
• Smart Background / Replace Background
• Expand
• Bleed
• Balance

Error Handling

The SDK converts API errors into Python exceptions for easier debugging:

• ApiError: Raised for non-20x HTTP responses.
• ApiAuthenticationError: Raised for authentication failures.
• ValueError: Raised for invalid payloads.

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:

• httpx, (MIT): Used as a http client

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.