[Alpha] Templating mode

Warning: Templating mode is available as an alpha feature.

This means that the feature (or parts of it) might be deprecated with two week warning.

Overview

Templating Mode enables the scalable generation of personalized and visually consistent images by connecting predefined design templates with dynamic content.

By creating a reusable image layout (a template) in the Photoroom editor and assigning unique identifiers to each customizable layer, developers can programmatically inject content—like text, product images, or branding elements—through API calls.

This approach is ideal for automating image creation for use cases such as product listings, ads, social media creatives, and more.

Step 1: Create your template

  1. Go to https://app.photoroom.com/create.

  2. Start a design from an image or from a Photoroom template. For example, open or upload an image in the Design tab.

  3. Turn the design into a template to access the templating features (click on the ellipsis ... button in the top menu bar, then on the Turn into template option).

  4. You can now add your image and text layers.

  5. On any text (or image) layer you can toggle on the Replaceable Text toggle (respectively the Replaceable Subject toggle). You can then edit the Unique ID field to give each of your layer a clear name.

  6. Make the template public to enable the API to access it: select Public link from the sharing settings. This means the template is public only to the people who know about this specific template ID. It enables the API to have access to your template.

  7. Click on the Preview tab, and click on the template ID at the bottom of this tab. This copies the template ID in your clipboard.

You now have a template with replaceable layers each identified by a unique ID. The template is publicly shared so that the API can access it.

Step 2: Create images through the API

The key is to keep track of the Unique IDs defined in your template for each layer, as they will be reused in your API calls.

Here is an example API call:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --form templateId=YOUR_TEMPLATE_ID \
  --form 'layers.author.text.content=Tom C.' \
  --form 'layers.review.text.content=”Nice product, I love it“' \
  --form 'layers.product.image.imageUrl=https://images.unsplash.com/photo-1541643600914-78b084683601?q=80&w=1200&auto=format&fit=crop'
Example output

The first attribute needed is templateId, which allows you to connect the API to your template.

All layer attributes are set using layers.UNIQUE_ID.image.ATTRIBUTE or layers.UNIQUE_ID.text.ATTRIBUTE (with UNIQUE_ID replaced by the actual layer unique id, and ATTRIBUTE being replaced by the attribute you want to target).

Here is a list of all attributes:

  • text layer

    • content (string): replaces the text content

    • foregroundColor (hexadecimal color string): replaces the text color

    • backgroundColor (hexadecimal color string): replaces the background color

    • font (string): replaces the font of the text (refer to the Photoroom editor for the full list of available fonts)

  • image layer

    • imageFile (binary): replaces the image (can only specify one of imageFile and imageUrl)

    • imageUrl (url string): replaces the image (can only specify one of imageFile and imageUrl)

    • removeBackground (auto or never): choose whether to remove the background of this image (defaults to auto)

    • useForAIBackground (auto or never): choose whether the image is taken into account when building the AI background (defaults to auto), this is only useful if you have defined an AI background in your template or API call.

    • horizontalAlignment (left, center or right): defines the horizontal alignment of the image within its box (defaults to auto)

    • verticalAlignment (top, center or bottom): defines the vertical alignment of the image within its box (defaults to auto)

    • margin (percentage string like 10% or decimal number like 0.1): defines margins around the object

      • you can use marginTop, marginRight, marginBottom, marginLeft if you want to specify different margins

    • padding (percentage string like 10% or decimal number like 0.1): defines padding around the object, the padding will be ignored on each side where the segmented object is cropped

      • you can use paddingTop, paddingRight, paddingBottom, paddingLeft if you want to specify different paddings

    • segmentation: Enables text-guided segmentation for this image. If removeBackground is never, the result will be "zoomed" to the segmented subject.

      • segmentation.prompt: A textual description of what the segmentation should keep, for example book,pen,ball

      • segmentation.negativePrompt (optional): A textual description of what the segmentation should remove

      • segmentation.mode: either keepSalientObject or ignoreSalientObject, default ignoreSalientObject. If it's keepSalientObject, the salient object of the image (i.e. what the default segmentation would have kept) will also be kept by the segmentation in addition to the prompt.

Note: the removeBackground=never and useForAIBackground=never are great when used with logos, so that only your products have their background removed and does not affect the AI background.

Here is an example of a more complex API call:

curl --request POST \\
  --url https://image-api.photoroom.com/v2/edit \\
  --header 'x-api-key: YOUR_API_KEY' \\
  --form templateId=YOUR_TEMPLATE_ID \\
  --form 'layers.author.text.content=Tom C.' \\
  --form layers.author.text.foregroundColor=DC143C \\
  --form layers.author.text.backgroundColor=fe9167 \\
  --form 'layers.review.text.font=Permanent Marker' \\
  --form 'layers.rating.text.content=★ ★ ★ ★ ☆' \\
  --form 'layers.review.text.content=”Nice product, I love it“' \\
  --form 'layers.cta.text.content=BUY NOW' \\
  --form 'layers.product.image.imageUrl=https://images.unsplash.com/photo-1541643600914-78b084683601?q=80&w=1200&auto=format&fit=crop' \\
  --form layers.product.image.removeBackground=auto \\
  --form layers.product.image.useForAIBackground=auto \\
  --form layers.product.image.horizontalAlignment=center \\
  --form layers.product.image.verticalAlignment=center \\
  --form layers.product.image.margin=0.1
Example output

Frequently Asked Questions (FAQ)

  • How many images can I replace (in the same row)?

    • There is a maximum of 10 replaceable images at the moment.

Previous[Alpha] Create Any ImageNext[Legacy] Image Editing API v1 In-Depth Tutorial

Last updated

Was this helpful?