Photo Studio

Overview

Photo Studio is Upvendo's built-in image editing and management tool that allows merchants to upload, enhance, and manage product photos directly within the backoffice. It integrates with external AI-powered services (PhotoRoom and Remove.bg) to offer professional background removal and photo editing capabilities, producing high-quality product images for use across menus, kiosks, and online ordering channels.

The feature consists of two main components: an image library for uploading and managing content, and an AI-powered processing pipeline that supports background removal, background color application, shadow effects, and custom sizing.

Purpose

This page lets you upload product images, remove backgrounds using AI, apply custom background colors and shadow effects, and manage a library of processed photos that can be used throughout the platform.

Key Concepts

• Photo Processing Provider: The external AI service used for image manipulation. Upvendo supports two providers -- PhotoRoom (premium quality, specialized for product photography) and Remove.bg (cost-effective at approximately $0.09/image). The default provider is configurable via services.photo_processing.default_provider. The factory pattern (PhotoProcessingFactory) selects the appropriate service at runtime.
• Background Removal: An AI-powered operation that isolates the subject of an image by stripping away the background, producing a transparent PNG. This is handled via the PhotoRoom /v1/segment endpoint or the Remove.bg /v1.0/removebg endpoint. Both providers accept the raw image file and return the processed result as base64-encoded data.
• Photo Editing: An advanced operation (PhotoRoom v2 only) that not only removes backgrounds but can apply custom background colors (hex format converted to RRGGBBAA with full opacity appended), shadow modes, custom output sizes, and configurable padding (default 10%). Uses the PhotoRoom /v2/edit endpoint. Remove.bg does not natively support photo editing; it only performs background removal.
• Content Entity: Each uploaded photo is stored as a Content document in MongoDB with source: photo_studio (from the ImageSources::PhotoStudio enum). The content is uploaded to Cloudflare Images and tracked with both a main cloudflare_image_id and a cloudflare_receipt_id for receipt-variant images. The ContentTrait handles the upload logic.
• Photo Processing Factory: A factory pattern class (PhotoProcessingFactory) that implements the PhotoProcessingInterface contract. It selects the appropriate processing service based on the provider parameter or falls back to the configured default. If no provider is specified, it tries PhotoRoom first (checking isConfigured()), then Remove.bg, and logs a warning if neither has API keys set.

Route

• Backoffice Route: /photo-studio
• Backend Controller: app/Http/Controllers/Api/PhotoStudioController.php
• Orchestrator: app/Services/Orchestrators/PhotoStudioOrchestrator.php
• Service: app/Services/PhotoStudio/PhotoStudioService.php
• Processing Services: app/Services/PhotoStudio/PhotoRoomService.php, app/Services/PhotoStudio/RemoveBgService.php
• Factory: app/Services/PhotoStudio/PhotoProcessingFactory.php
• Backoffice Utilities: src/utils/photoroom.ts, src/services/photoTemplateService.ts

Actions

Upload Image

Upload a new product image to the Photo Studio library. The image is validated using the UploadContentRequest (must be a valid image file), then processed through the ContentTrait.handleMediaUpload method which uploads it to Cloudflare Images with the photo_studio source tag and stores it as a Content document. The image is saved under the photo-studio directory path.

• Endpoint: POST /api/photo-studio
• Request: UploadContentRequest -- requires image field (valid image file)
• Response: JSON object with content details including the generated ID and image URL

View All Images

Retrieve the complete Photo Studio image library for the current vendor. Maps through all Content entities and returns each one's id and image_url (using the original variant from Cloudflare Images).

• Endpoint: GET /api/photo-studio
• Response: JSON array of {id, image_url} objects wrapped in a data key

Update Image

Replace an existing Photo Studio image with a new upload. The system follows a safe update pattern:

1. Retrieves the existing Content document and stores the old cloudflare_image_id and cloudflare_receipt_id
2. Performs the new upload using handleMediaUpload with isPhotoStudioUpdate: true
3. Only after a successful upload and database update, deletes the old Cloudflare images
4. Logs success or warning messages for each deletion attempt

• Endpoint: PUT /api/photo-studio/{id}
• Request: UploadContentRequest -- requires image field
• Response: Success response

Delete Image

Permanently remove a Photo Studio image from the library. Delegates to the ContentService.delete method which removes the Content document.

• Endpoint: DELETE /api/photo-studio/{id}
• Response: Success response

Remove Background

Process an uploaded image through the AI background removal service. The controller validates the request inline with specific rules, then delegates to the selected provider via the factory.

• Endpoint: POST /api/photo-studio/remove-background
• Parameters: image (required, file, max 10 MB), provider (optional), size, type, format
• Response: Binary PNG image data with Content-Type: image/png header
• PhotoRoom behavior: Posts to /v1/segment with the image file
• Remove.bg behavior: Posts to /v1.0/removebg with size, type, and format options; returns credit charge info via X-Credits-Charged header

Edit Photo

Process an uploaded image with advanced editing options. Only fully functional with the PhotoRoom v2 provider.

• Endpoint: POST /api/photo-studio/edit-photo
• Parameters: image (required, file, max 10 MB), provider (optional), outputSize, backgroundColor, shadowMode
• Response: Binary PNG image data with Content-Type: image/png header
• PhotoRoom behavior: Converts hex color to RRGGBBAA format, sets output size (default 1000x1000), padding (default 0.1), and shadow mode. Posts to /v2/edit
• Remove.bg behavior: Falls back to background removal only; editing features are not supported

Get Account Info

Retrieve account information for the configured photo processing provider, including remaining API credits and usage data.

• Endpoint: GET /api/photo-studio/account-info
• Parameters: provider (optional)
• Remove.bg response: JSON with account details from the /v1.0/account endpoint
• PhotoRoom response: Returns an error as PhotoRoom does not provide a public account info endpoint

Fields

Field	ID	Type	Required	Validation
Image	image	File (image)	Yes	Must be a valid image file
Provider	provider	String	No	One of: photoroom, removebg
Size	size	String	No	One of: auto, preview, small, medium, hd, full, 4k
Type	type	String	No	One of: auto, person, product, car
Format	format	String	No	One of: png, jpg, zip
Output Size	outputSize	String	No	Dimensions string (e.g., 1000x1000)
Background Color	backgroundColor	String	No	Hex color code (e.g., #FF0000); converted to RRGGBBAA
Shadow Mode	shadowMode	String	No	Shadow effect style; values disabled, none, or empty string disable shadows

Business Rules

• Uploaded images for background removal and editing have a maximum file size of 10 MB (max:10240 validation rule on the controller).
• Library image uploads via the CRUD endpoints use the UploadContentRequest which requires a valid image file with no explicit size limit beyond PHP/server defaults.
• When updating an existing Photo Studio image, old Cloudflare images are only deleted after the new upload succeeds, ensuring no data loss on failure. Both the main image and receipt-variant image are cleaned up independently.
• The system uses a factory pattern with fallback logic: if the configured provider is unavailable, it tries PhotoRoom first (checking isConfigured()), then Remove.bg, and logs a warning if neither is configured. The isConfigured() method checks whether the API key is non-empty.
• Photo Studio images are tagged with ImageSources::PhotoStudio so they can be distinguished from direct_upload, existing, url, external, square, and suggestions_api sources when filtering or querying content.
• All photo processing API calls have a 60-second timeout (timeout(60)) to accommodate large image processing operations without premature failures.
• The PhotoRoom edit endpoint converts hex colors from #RRGGBB to RRGGBBFF format (appending full opacity) before sending to the API.
• Background removal results are decoded from base64 and returned as raw binary PNG data rather than JSON, making them directly usable for display or further processing.

Customer Impact

• Kiosk: Higher-quality product images with clean backgrounds improve the visual presentation of menu items on self-service kiosks, leading to better customer engagement and potentially higher order values.
• Online Ordering: Professional product photography with consistent backgrounds creates a polished online storefront that can increase conversion rates. Customers are more likely to order items with appealing images.
• Receipts: Updated images propagate to receipt variants via Cloudflare Images, ensuring consistent branding across all touchpoints including printed and digital receipts.
• QR Ordering: Product images from Photo Studio appear on the table QR ordering interface, enhancing the dine-in ordering experience.

FAQs

What image formats are supported for upload?

Photo Studio accepts any standard image format recognized by Laravel's image validation, including JPEG, PNG, GIF, BMP, SVG, and WebP.

Which photo processing provider should I choose?

PhotoRoom is recommended for product photography as it offers higher quality results and advanced editing features (background color, shadows, custom sizing with padding). Remove.bg is a cost-effective alternative at approximately $0.09 per image but only supports background removal without advanced editing.

Can I use Photo Studio images for menu items?

Yes. Photo Studio images are stored as Content entities with the photo_studio source. When creating or editing items or display groups, you can select photo_studio as the image source to reference images from the Photo Studio library.

What happens if neither API key is configured?

The system will still allow image upload and management via the CRUD endpoints, but background removal and editing operations will fail with an error. A warning is logged at service construction time when API keys are missing.

Is there a limit on the number of images I can store?

There is no hard limit on the number of Photo Studio images within Upvendo. Storage is managed through Cloudflare Images, and costs scale with usage based on the Cloudflare plan.

Can I switch between providers for different operations?

Yes. Each processing request (remove-background, edit-photo, account-info) accepts an optional provider parameter. You can use PhotoRoom for editing and Remove.bg for background removal within the same workflow.

What is the default output size for edited photos?

The PhotoRoom edit endpoint defaults to 1000x1000 pixels with 0.1 (10%) padding if no custom output size is specified.

Troubleshooting

Background removal returns a 400 error

Check that the provider API key is correctly configured in the environment variables (PHOTOROOM_API_KEY or REMOVEBG_API_KEY). Verify the image file is under 10 MB and is a valid image format. Check the application logs for the specific error message from the provider API. For Remove.bg, look for error details in the response's errors[0].title field. For PhotoRoom, check the error.message or detail field.

Image upload succeeds but the image URL is broken

This typically indicates a Cloudflare Images configuration issue. Verify that the Cloudflare account ID and API token are correctly set in the environment. Check that the CloudflareImageService can successfully upload and serve images. Ensure the Content document was created with valid cloudflare_image_id.

Old images are not being cleaned up after update

The system logs warnings when old Cloudflare image deletion fails. Check the logs for messages containing "Failed to delete old Cloudflare image after photo studio update" or "Failed to delete old Cloudflare receipt image after photo studio update" and verify Cloudflare API connectivity and permissions.

Edit photo returns different results than expected

Photo editing with background color and shadows is only fully supported by the PhotoRoom provider (v2 API). If using Remove.bg, only background removal is performed; background color and shadow effects must be applied client-side. Ensure the provider parameter is set to photoroom for full editing support.

Account info endpoint returns an error for PhotoRoom

This is expected behavior. PhotoRoom does not provide a public account info endpoint. The account info feature only works with the Remove.bg provider, which exposes account details including credit balance.

Processing is slow or timing out

Photo processing operations can take up to 60 seconds depending on image size and provider load. If operations consistently time out, check the image file size (reduce if over 5 MB), verify network connectivity to the provider API endpoints, and check provider service status pages.

Technical Details

Provider Architecture

Both photo processing providers implement the PhotoProcessingInterface contract, which defines three methods: removeBackground(UploadedFile $image, array $options): array, editPhoto(UploadedFile $image, array $options): array, and getAccountInfo(): array. Each method returns a standardized response array with success (boolean), data (base64-encoded image or account info), error (error message or null), and credits_charged (float or null, only populated by Remove.bg).

PhotoRoom API Versions

PhotoRoom uses two API versions for different operations:

• v1 (https://sdk.photoroom.com/v1): Used for background removal via the /segment endpoint. Accepts an image file and returns the segmented image with transparent background.
• v2 (https://image-api.photoroom.com/v2): Used for advanced photo editing via the /edit endpoint. Supports background.color, outputSize, padding, and shadow.mode parameters in addition to background removal.

Cloudflare Image Lifecycle

When a Photo Studio image is uploaded, the ContentTrait.handleMediaUpload method creates a Content document with Cloudflare image references. The lifecycle includes: upload to Cloudflare (generating cloudflare_image_id and cloudflare_receipt_id), serving via CDN variants (original, kioskgroup, receipt), and cleanup on update/delete. The safe update pattern ensures old images are only removed after the new upload succeeds, with detailed logging for both success and failure cases.

Image Source Enum

The ImageSources enum includes PhotoStudio alongside DirectUpload, Existing, URL, External, Square, and SuggestionsAPI. This enum is used when uploading images to tag their origin, allowing the system to distinguish between manually uploaded images, AI-processed photos, and externally imported images throughout the platform.

Backoffice Integration

The backoffice frontend includes two supporting modules for Photo Studio: src/utils/photoroom.ts provides client-side utilities for interacting with the PhotoRoom service, and src/services/photoTemplateService.ts manages photo templates for consistent product photography. These work alongside the backend API to provide a complete image editing workflow within the backoffice interface.

Assistant Guidance

When users ask about Photo Studio, help them understand the two main capabilities: (1) image library management (upload, view, update, delete) and (2) AI-powered image processing (background removal, photo editing). Clarify the difference between the two providers and recommend PhotoRoom for product photography use cases where background color and shadow effects are needed. If a user reports processing errors, first check API key configuration in environment variables. For questions about using Photo Studio images elsewhere in the platform, explain that images are stored as Content entities and can be referenced from items and display groups by selecting the photo_studio image source. Remind users that the account info endpoint only works with Remove.bg.

Relations

Depends On

• Cloudflare Images: Required for image hosting, variant generation (original, receipt), and delivery via CDN.
• PhotoRoom API: External service for premium AI-powered background removal (v1) and photo editing (v2).
• Remove.bg API: External service for cost-effective AI-powered background removal.
• Content Service: Manages the underlying Content documents in MongoDB via ContentService and ContentTrait.
• Vendor Context: Photo Studio operations are scoped to the current vendor via VendorTrait.

Affects

• Items: Photo Studio images can be used as product images for menu items via the photo_studio image source.
• Display Groups: Display group images can be sourced from the Photo Studio library.
• Menus: Menu presentation quality is directly impacted by the quality of product images produced by Photo Studio.
• Online Ordering: Customer-facing product image quality affects ordering decisions and conversion rates.
• Kiosk: Visual presentation on self-service kiosks depends on image quality and consistency.
• Categories: Category images can also benefit from Photo Studio processing for consistent visual branding across the menu.