PhotoRoom Getting Started: Account, Keys, First Request (2026)

Getting started overview

Getting started with the PhotoRoom API involves a sequence of steps to configure your environment and make your first programmatic call. The process begins with account creation, followed by API key generation, and culminates in sending a request to an API endpoint. PhotoRoom provides a free tier with 10 API credits for initial testing, allowing developers to experiment with its core functionalities, such as background removal and image editing, without an immediate financial commitment (PhotoRoom API pricing details).

The API is designed to support common image manipulation tasks, making it suitable for applications requiring automated image processing, particularly in e-commerce and content creation (PhotoRoom API documentation). This guide outlines the essential steps from setting up your account to executing your first API call, ensuring a foundation for integrating PhotoRoom's capabilities into your projects.

The following table provides a quick reference for the essential setup steps:

Create an account and get keys

To access the PhotoRoom API, you must first create a PhotoRoom account. This account provides access to the developer dashboard, where API keys are managed and usage is tracked.

1. Navigate to the PhotoRoom API documentation: Visit the official PhotoRoom API documentation page.
2. Sign Up: Look for a "Sign Up" or "Get Started" option. You may be prompted to create an account using an email address, Google, or Apple ID.
3. Access Developer Dashboard: After successful registration and login, you should be directed to your PhotoRoom developer dashboard.
4. Generate API Key: Within the dashboard, locate the "API Keys" section. PhotoRoom typically provides an option to generate a new API key. It is common practice to generate separate keys for different environments (e.g., development, production) to enhance security and simplify key rotation (AWS Access Keys best practices).
5. Secure Your Key: Once generated, copy your API key. Treat it as sensitive information. Avoid hardcoding it directly into your application code, especially in client-side applications. Instead, use environment variables or a secure configuration management system.

Your API key is a unique identifier that authenticates your requests to the PhotoRoom API. Without it, API calls will be rejected with an authentication error.

Your first request

After obtaining your API key, you can make your first request to the PhotoRoom API. This example uses the Background Removal API, a core PhotoRoom feature, to process an image. We will demonstrate using cURL for simplicity, as it is readily available in most development environments, and then provide a Python example.

Using cURL

To remove the background from an image using cURL, you will send a POST request to the /v1/edit endpoint. Replace YOUR_API_KEY with your actual PhotoRoom API key and path/to/your/image.jpg with the path to your local image file.

curl -X POST \ \
  https://api.photoroom.com/v1/edit \ \
  -H 'X-Api-Key: YOUR_API_KEY' \ \
  -H 'Content-Type: multipart/form-data' \ \
  -F 'image_file=@path/to/your/image.jpg' \ \
  -F 'size=auto' \ \
  -F 'background_color=transparent' \ \
  -o output_image.png

This command instructs cURL to:

• -X POST: Send a POST request.
• https://api.photoroom.com/v1/edit: Target the API endpoint for editing.
• -H 'X-Api-Key: YOUR_API_KEY': Include your API key in the X-Api-Key header for authentication.
• -H 'Content-Type: multipart/form-data': Specify the content type for file uploads.
• -F 'image_file=@path/to/your/image.jpg': Attach your image file as multipart/form-data. The @ prefix tells cURL to read the content from a file.
• -F 'size=auto': Request automatic sizing.
• -F 'background_color=transparent': Specify a transparent background for the output image.
• -o output_image.png: Save the processed image to a file named output_image.png.

Using Python

For Python developers, the requests library is a common choice for making HTTP requests. First, ensure you have the library installed:

pip install requests

Then, use the following Python code:

import requests

api_key = "YOUR_API_KEY"
image_path = "path/to/your/image.jpg" # Replace with your image file path
output_path = "output_image.png"

url = "https://api.photoroom.com/v1/edit"

headers = {
    "X-Api-Key": api_key
}

files = {
    "image_file": open(image_path, "rb")
}

data = {
    "size": "auto",
    "background_color": "transparent"
}

try:
    response = requests.post(url, headers=headers, files=files, data=data)
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)

    if response.status_code == 200:
        with open(output_path, "wb") as f:
            f.write(response.content)
        print(f"Image saved to {output_path}")
    else:
        print(f"Error processing image: {response.text}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")
finally:
    # Ensure the file handle is closed
    if 'image_file' in files and not files['image_file'].closed:
        files['image_file'].close()

This script:

• Sets your API key and image paths.
• Opens the image file in binary read mode ("rb").
• Constructs headers with your API key.
• Prepares the data payload specifying output preferences.
• Sends a POST request and saves the binary response content as an image file.
• Includes error handling for network issues and API-specific errors.

Common next steps

After successfully making your first API call, consider these next steps to further integrate and optimize your PhotoRoom API usage:

1. Explore Additional Endpoints: Review the PhotoRoom API reference for other available endpoints, such as those for object removal, batch processing, or different image adjustments. Understanding the full range of functionalities can help you expand your application's capabilities.
2. Implement Error Handling: Develop robust error handling for various API responses. This includes HTTP status codes (e.g., 400 for bad request, 401 for unauthorized, 429 for rate limiting, 500 for internal server errors) and specific error messages returned in the API's JSON body. Proper error handling improves application stability and user experience.
3. Manage API Keys Securely: Reinforce practices for securing your API keys. Avoid embedding them directly in client-side code or public repositories. Use environment variables, secure secret management services, or a proxy server to protect your credentials. The Google Cloud API keys best practices offer general guidance on this topic.
4. Monitor Usage and Billing: Regularly check your API usage in the PhotoRoom developer dashboard. Understand the credit consumption rates for different operations and monitor your remaining credits to avoid service interruptions. Review the PhotoRoom API pricing page to plan for scaling.
5. Optimize Image Processing: Experiment with different parameters (e.g., size, format, background_color) to optimize image quality and file size for your specific use cases. For batch processing, consider how to efficiently send multiple images while respecting rate limits.
6. Integrate into Your Application: Integrate the API calls into your existing application workflow. This might involve creating a dedicated service layer for image processing or embedding calls within an existing microservice.

Troubleshooting the first call

When encountering issues with your first PhotoRoom API call, consider the following common troubleshooting steps:

• Check API Key: Ensure your API key is correctly copied and included in the X-Api-Key header. A common error is a typo or an expired/revoked key. Double-check that no extra spaces or characters are present.
• Verify Endpoint URL: Confirm that the API endpoint URL (e.g., https://api.photoroom.com/v1/edit) is correct and matches the documentation.
• Inspect Request Headers: Confirm that all required headers, especially X-Api-Key and Content-Type (for multipart/form-data requests), are correctly set. Incorrect MIME types can prevent file uploads from being processed (MDN Content-Type documentation).
• Examine Request Body/Payload: If sending data in the request body (e.g., form fields for size or background_color), ensure it is correctly formatted. For file uploads, verify that the file path is correct and the file is accessible to the script.
• Review API Response: Always inspect the HTTP status code and the response body.
• 401 Unauthorized: Typically indicates an issue with your API key (missing, invalid, or expired).
• 400 Bad Request: Suggests an issue with your request parameters or format. The response body often contains a more specific error message.
• 429 Too Many Requests: You've exceeded the rate limits. Implement a retry mechanism with exponential backoff.
• 5xx Server Error: Indicates an issue on PhotoRoom's side. If persistent, check PhotoRoom's status page or contact support.
• Check File Access: For file uploads, ensure your script has the necessary permissions to read the image file specified by image_file=@path/to/your/image.jpg.
• Network Connectivity: Verify your internet connection and ensure no firewalls or proxy settings are blocking the request to api.photoroom.com.
• Consult Documentation: Re-read the relevant sections of the PhotoRoom API documentation, especially endpoint-specific requirements and error codes.
• Use Verbose Logging: If using cURL, add -v to get more verbose output, which can reveal details about the request and response headers. For Python, add print statements to log intermediate values and the full response.