Pebblely API Documentation
Sign up or log in to our API dashboard herePebblely 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}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: intExample
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"]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 = ""Response
Response: # "data" - Base64 representation of the resulting image data: str # "credits" - Number of remaining credits credits: intExample
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")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: strResponse
Response: # "data" - Base64 representation of the resulting image data: str # "credits" - Number of remaining credits credits: intExample
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")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 = 1024Response
Response: # "data" - Base64 representation of the resulting image data: str # "credits" - Number of remaining credits credits: intExample
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")
PebblelyProduct Photography