Pebblely API Documentation

Sign up or log in to our API dashboard here

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

Sign up here to get an access token and purchase credits.


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.


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, except for upscaling to 2048, which consumes 4 credits.


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

Create Background

POST /create-background/v1

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:    # "image" - Base64 representation or URL of image    image: 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 = ""
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/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>",        "theme": "Surprise me",    })# 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.

As of now, this endpoint takes around ~8 seconds for upscaling to 1024, and ~40 seconds for upscaling to 2048.

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