Pebblely API Documentation

Pebblely provides an API for individuals and companies that are considering processing large volumes of product photos.

ℹ️

If you are looking to generate on-model photos, check out our Pebblely Fashion API.

Authentication

All Pebblely API queries require a valid access token, which you can obtain by signing up for API access.

Include your token as a X-Pebblely-Access-Token header on all API queries.

At the moment, accessing the API via client-side will return a CORS error. Instead, you should access the API via server-side instead, which should resolve the CORS issue, as well as keep your API key secure.

Endpoints

All Pebblely API endpoints follow the following format:

https://api.pebblely.com/{endpoint}

Copy

By default, all API keys are rate-limited at 1 query per second. The latency for each endpoint varies, see the specific endpoint for more details. Contact us if you have specific requirements around rate-limiting and latencies.

Each API query consumes 1 credit.

Note that there is a maximum file size of 5MB for all images uploaded.

Get Credits

GET /credits/v1

Retrieves the number of remaining credits for an account.

Response

Response:    # "credits" - Number of credits remaining    credits: int

Copy

Example

get_credits.py

import requestsendpoint_url = "https://api.pebblely.com/credits/v1/"response = requests.get(    endpoint_url,    headers={        "X-Pebblely-Access-Token": "<YOUR ACCESS TOKEN>",    },)remaining_credits = response.json()["credits"]

Copy

Get Themes

GET /themes/v1

Retrieves the list of themes and their respective thumbnails.

Response

Response:    # List of Theme objects, where each object comprises the following keys and values    #   "label": str - Label of theme    #   "thumbnail": str - Sample thumbnail URL    List[Dict[str, str]]

Copy

Example

get_themes.py

import requestsendpoint_url = "https://api.pebblely.com/themes/v1/"response = requests.get(    endpoint_url)themes = response.json()print(len(themes)) # Should print number of themesprint(themes[0]["label"]) # Should print "Surprise me"

Copy

Create Background

POST /create-background/v2

The /create-background/v1 endpoint is being deprecated. Use the v2 endpoint instead, which supports multiple products.

Use the create-background endpoint with a product image where the background has been removed to create a photo of your product in a new setting.

This endpoint works best with square inputs for now. If you try this endpoint with a rectangular image, the input will be padded on both sides, vertically or horizontally, to form a square image before rendering the background. The output image will be 512 by 512 pixels - you can use the upscale endpoint to increase the size of the image.

More flexible aspect ratios will be added soon.

This endpoint takes ~5 seconds for a 512 by 512 input image.

Note The input image should be a PNG with transparent background. If you do not have an appropriate image, try using the remove-background endpoint first.

Request body

RequestBody:    # "images" - A list of strings, which are Base64 representations or URLs of images    images: List[str]    # "theme" - One of ["Surprise me", "Studio", "Outdoors", "Silk", "Cafe", "Tabletop", "Kitchen", "Flowers", "Nature", "Beach", "Bathroom", "Furniture", "Paint", "Fruits", "Water", "Pebbles", "Snow"]    # This is ignored if `description` is supplied    theme: str = "Surprise me"    # "description" - Custom description of the created image    description: str = ""    # "style_color" - Hex string representing a color e.g. "#FFFFFF"    style_color: str = None    # "style_image" - Base64 representation or URL of image    style_image: str = None    # "negative" - A list of comma-separated attributes that should be discouraged from the image    negative: str = ""    # "generate_plus" - Whether to use the Generate+ pipeline, which takes longer (~15s) with better quality    generate_plus: bool = False    # "transforms" - A List of Dicts that has the following parameters (all optional):    #   - "scale_x": float - Scale the product image horizontally    #   - "scale_Y": float - Scale the product image vertically    #   - "x": int - Translate the product image vertically    #   - "y": int - Translate the product image vertically    #   - "angle": float - Rotate the product clockwise, in degrees    # If no "transforms" is provided or is an empty List, the product images default to being centered in the 512 x 512 canvas    transforms: List[Dict] = []    # "autoresize" - Use this parameter to automatically resize and center your input image to fit the resulting output    autoresize: bool = False    # "height", "width" - Height and width of image, up to a maximum of 2048    # If only one dimension is provided, the other dimension defaults to the same value and a square image will be generated    height: int = 512    width: int = 512

Copy

Response

Response:    # "data" - Base64 representation of the resulting image    data: str    # "credits" - Number of remaining credits    credits: int

Copy

Example

create_background.py

import base64import ioimport requestsfrom PIL import Imageendpoint_url = "https://api.pebblely.com/create-background/v2/"response = requests.post(    endpoint_url,    headers={        "Content-Type": "application/json",        "X-Pebblely-Access-Token": "<YOUR ACCESS TOKEN>",    },    json={        "images": ["<YOUR IMAGE URL OR BASE64>"],        "theme": "Surprise me",        "transforms": [{            "scale_x": 1,            "scale_y": 1,            "x": 0,            "y": 0,            "angle": 0        }]    })# Process Base64 output and save locally image_b64 = response.json()["data"]image_encoded = image_b64.encode("utf-8")image_bytes = io.BytesIO(base64.b64decode(image_encoded))image = Image.open(image_bytes)image.save("image.jpg")

Copy

Remove Background

POST /remove-background/v1

Use the remove-background endpoint to remove the background from your product photo. The output from this endpoint can be used in the create-background endpoint to create a variety of settings for your product photo.

This endpoint takes in images of any aspect ratio.

This endpoint takes ~3 seconds for a 512 by 512 image.

Request body

RequestBody:    # "image" - Base64 representation or URL of image    image: str

Copy

Response

Response:    # "data" - Base64 representation of the resulting image    data: str    # "credits" - Number of remaining credits    credits: int

Copy

Example

remove_background.py

import base64import ioimport requestsfrom PIL import Imageendpoint_url = "https://api.pebblely.com/remove-background/v1/"response = requests.post(    endpoint_url,    headers={        "Content-Type": "application/json",        "X-Pebblely-Access-Token": "<YOUR ACCESS TOKEN>",    },    json={        "image": "<YOUR IMAGE URL OR BASE64>",    })image_b64 = response.json()["data"]image_encoded = image_b64.encode("utf-8")image_bytes = io.BytesIO(base64.b64decode(image_encoded))image = Image.open(image_bytes)image.save("image.png")

Copy

Upscale

POST /upscale/v1

Use the upscale endpoint to increase the resolution of your image. This endpoint can upscale the input up to 2048 by 2048 pixels.

This endpoint takes in images of any aspect ratio. For rectangular images, the resulting output's longer edge will be 1024 or 2048 pixels, depending on the size requested.

Request body

RequestBody:    # "image" - Base64 representation or URL of image    image: str    # "size" - Size of the image, one of [1024, 2048]    size: int = 1024

Copy

Response

Response:    # "data" - Base64 representation of the resulting image    data: str    # "credits" - Number of remaining credits    credits: int

Copy

Example

upscale.py

import base64import ioimport requestsfrom PIL import Imageendpoint_url = "https://api.pebblely.com/upscale/v1/"response = requests.post(    endpoint_url,    headers={        "Content-Type": "application/json",        "X-Pebblely-Access-Token": "<YOUR ACCESS TOKEN>",    },    json={        "image": "<YOUR IMAGE URL OR BASE64>",        "size": 1024,    })image_b64 = response.json()["data"]image_encoded = image_b64.encode("utf-8")image_bytes = io.BytesIO(base64.b64decode(image_encoded))image = Image.open(image_bytes)image.save("image.jpg")

Copy

Outpaint

POST /outpaint/v1

Use the outpaint endpoint to resize an image and intelligently inpaint missing sections if the desired canvas is larger than the initial image. This endpoint can return a result up to 2048 by 2048 pixels.

If the input image was generated using the create-background endpoint, we recommend providing the same settings in the request body (i.e. theme, description etc.) This will help create a more consistent outpainting result.

Request body

RequestBody:    # "image" - Base64 representation or URL of image    image: str    # "width" and "height" - Size of the image, up to a maxium of 2048    # If only one dimension is provided, the output will be a square image of that size    width: int = 512    height: int = 512    # "transform": - A dictionary or object that has the following parameters (all optional):    # If no "transform" is provided or is None, the product defaults to being centered in the canvas    transform = {        # "scale_x" - Scale the image horizontally        scale_x: float = 1.0,        # "scale_y" - Scale the image vertically        scale_y: float = 1.0,        # "x" - Translate the image horizontally        x: int = 0,        # "y" - Translate the image vertically        y: int = 0,        # "angle" - Rotate the image clockwise, in degrees        angle: float = 0.0,    }    # If the input image was generated using the `create-background` endpoint, we recommend providing the same settings below    # "theme" - One of ["Surprise me", "Studio", "Outdoors", "Silk", "Cafe", "Tabletop", "Kitchen", "Flowers", "Nature", "Beach", "Bathroom", "Furniture", "Paint", "Fruits", "Water", "Pebbles", "Snow"]    # This is ignored if `description` is supplied    theme: str = "Surprise me"    # "description" - Custom description of the created image    description: str = ""    # "style_color" - Hex string representing a color e.g. "#FFFFFF"    style_color: str = None    # "style_image" - Base64 representation or URL of image    style_image: str = None    # "negative" - A list of comma-separated attributes that should be discouraged from the image    negative: str = ""

Copy

Response

Response:    # "data" - Base64 representation of the resulting image    data: str    # "credits" - Number of remaining credits    credits: int

Copy

Example

outpaint.py

import base64import ioimport requestsfrom PIL import Imageendpoint_url = "https://api.pebblely.com/outpaint/v1/"response = requests.post(    endpoint_url,    headers={        "Content-Type": "application/json",        "X-Pebblely-Access-Token": "<YOUR ACCESS TOKEN>",    },    json={        "image": "<YOUR IMAGE URL OR BASE64>",        "width": 1024,    })image_b64 = response.json()["data"]image_encoded = image_b64.encode("utf-8")image_bytes = io.BytesIO(base64.b64decode(image_encoded))image = Image.open(image_bytes)image.save("image.jpg")

Copy

Inpaint

POST /inpaint/v1

Use the inpaint endpoint to inpaint an image using a mask. This endpoint can return a result up to 2048 by 2048 pixels.

Request body

RequestBody:    # "image" - Base64 representation or URL of image    image: str    # "mask" - Base64 representation or URL of binary mask, where non-zero values indicate sections to be inpainted - must be same dimensions as image    mask: str    # If the original image was generated using the `create-background` endpoint, we recommend providing the same settings below    # "theme" - One of ["Surprise me", "Studio", "Outdoors", "Silk", "Cafe", "Tabletop", "Kitchen", "Flowers", "Nature", "Beach", "Bathroom", "Furniture", "Paint", "Fruits", "Water", "Pebbles", "Snow"]    # This is ignored if `description` is supplied    theme: str = "Surprise me"    # "description" - Custom description of the created image    description: str = ""    # "style_color" - Hex string representing a color e.g. "#FFFFFF"    style_color: str = None    # "style_image" - Base64 representation or URL of image    style_image: str = None    # "negative" - A list of comma-separated attributes that should be discouraged from the image    negative: str = ""

Copy

Response

Response:    # "data" - Base64 representation of the resulting image    data: str    # "credits" - Number of remaining credits    credits: int

Copy

Example

inpaint.py

import base64import ioimport requestsfrom PIL import Imageendpoint_url = "https://api.pebblely.com/inpaint/v1/"response = requests.post(    endpoint_url,    headers={        "Content-Type": "application/json",        "X-Pebblely-Access-Token": "<YOUR ACCESS TOKEN>",    },    json={        "image": "<YOUR IMAGE URL OR BASE64>",        "mask": "<YOUR MASK URL OR BASE64>",    })image_b64 = response.json()["data"]image_encoded = image_b64.encode("utf-8")image_bytes = io.BytesIO(base64.b64decode(image_encoded))image = Image.open(image_bytes)image.save("image.jpg")

Copy

Contents

Pebblely API Documentation