# Quickstart Guide Here's a walkthrough of the latest API features: {% embed url="" %} ## Who is this API for? The Image Editing API enables anyone to easily create high-quality images. This is what a typical call to the API looks like: ```sh curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/absolute/path/to/image.jpg \ --form removeBackground=true \ --form background.color=FFFFFF \ --form padding=0.15 \ --form shadow.mode=ai.soft \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](https://docs.photoroom.com/getting-started/introduction#how-can-i-get-my-api-key). {% endhint %} And these are examples of results that this API call produces: | *(original image)* | *(result image)* | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FF9aePxDAi87gxSXUI7q0%2Farno-senoner-oCXVxwTFwqE-unsplash.jpg?alt=media\&token=2bdd3141-664d-49fe-b0a9-5523e28d06b6) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F8AU7Zwk7FAJHKs0mw5Aj%2Farno-senoner-oCXVxwTFwqE-unsplash.png?alt=media\&token=3f5e262d-c5a1-4c6c-b0cc-a57f3ecffbad) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FzosfeByML0TIFxRcisuL%2Fdylan-shoemaker-P5tHZv-QTCA-unsplash.jpg?alt=media\&token=28f7ebcf-93dc-481c-9f7f-0d7954b04961) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fk8R35WdY4aFNBD5u7ypE%2Fdylan-shoemaker-P5tHZv-QTCA-unsplash.png?alt=media\&token=0589787b-f1d0-4677-a874-5b0d156cdd81) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FsKHxqVDsGHipUBBybOxG%2Fjon-tyson-aR6RjBC_bF0-unsplash.jpg?alt=media\&token=548edb41-c3dd-4c2e-9447-29e415d36a89) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F2xRqBNJXvHhR3GNuntdj%2Fjon-tyson-aR6RjBC_bF0-unsplash.png?alt=media\&token=38409992-83a0-4012-b492-f92be1e1a8b0) | Let's go over the parameters of this API call. #### `imageFile=@/absolute/path/to/image.jpg` This parameter represents the input image that you want to edit. This image can be provided either: * as a file, using the parameter `imageFile` * as a URL, using the parameter `imageUrl` More details about maximum file size, resolution and image formats are [available here](https://docs.photoroom.com/image-editing-api-plus-plan/file-size-resolution-and-format). #### `removeBackground=true` This parameter specifies that the background of the input image should be removed. {% hint style="info" %} `removeBackground` is set to `true` by default, so you can omit it when you want the background to be removed {% endhint %} #### `background.color=FFFFFF` This parameter creates a new background that consists of a white solid color. Alternatively to using a solid color, you can also opt for: * having a transparent background (this is this the default behavior) * using a [static image](https://docs.photoroom.com/image-editing-api-plus-plan/static-background) * creating an [AI Background](https://docs.photoroom.com/image-editing-api-plus-plan/ai-backgrounds) #### `padding=0.15` This parameter adds 15% of padding around the subject, for a more visually pleasing result. The positioning of the subject in the result image is fully customizable, you can [read more about it here](https://docs.photoroom.com/image-editing-api-plus-plan/positioning). #### `shadow.mode=ai.soft` This parameter adds a realistic shadow to the subject, which helps the result image look more natural. The look of the shadow can be customized, you can [read more about it here](https://docs.photoroom.com/image-editing-api-plus-plan/ai-shadows). ## How do I configure my first API call? We designed the Image Editing API so that it’s both very powerful and very easy to use. There are two ways to start using the Image Editing API: 1. If you already know which feature you're looking for, then you can simply use the *Try it now!* button that's available on the documentation page of that feature:
2. If not, then you can use the search bar at the top of the documentation and simply describe the output that you want to achieve:
{% hint style="info" %} Please note that you can make API calls for free using our [Sandbox mode](https://docs.photoroom.com/getting-started/pricing#can-i-get-free-api-calls). {% endhint %} ## Which endpoints are available? The Image Editing API exposes two endpoints. ### GET endpoint ```http GET https://image-api.photoroom.com/v2/edit ``` The `GET` endpoint expects you to: * configure the edits you want to apply through query string arguments * provide the input image as a URL, through the argument `imageUrl` This means that the images you process through that endpoint must already be hosted on the Internet. Here's an example of an API call made using the `GET` endpoint: {% code overflow="wrap" %} ```sh curl 'https://image-api.photoroom.com/v2/edit?shadow.mode=ai.soft&background.color=FFFFFF&padding=0.1&imageUrl=URL_OF_YOUR_IMAGE' \ --header 'x-api-key: YOUR_API_KEY' \ --output result-get-endpoint.png ``` {% endcode %} {% hint style="info" %} The full API reference documentation of this endpoint is [available here](https://docs.photoroom.com/getting-started/api-reference-openapi#get-v2-edit) {% endhint %} ### POST endpoint ```http POST https://image-api.photoroom.com/v2/edit ``` The `POST` endpoint allows you to: * directly upload an image file, through the argument `imageFile` * configure the edits through the body of the request rather than the query string Here's an example of an API call made using the `POST` endpoint: ```sh curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/absolute/path/to/image.jpg \ --form shadow.mode=ai.soft \ --form background.color=FFFFFF \ --form padding=0.1 \ --output result-post-endpoint.png ``` Try it now! {% hint style="info" %} The full API reference documentation of this endpoint is [available here](https://docs.photoroom.com/getting-started/api-reference-openapi#post-v2-edit) {% endhint %} ## Will the API make alterations to my products? No, for most use cases the Image Editing API will **not make** alterations to your products. By default, the API will: 1. remove the background of the original image, to isolate its main subject 2. reposition and add effects around that main subject With this approach, it's simply not possible to introduce alterations, such as modifying a logo or a brand name. The Image Editing API does offer some features that can, however, introduce alterations. Here's their exhaustive list: * [AI Relight](https://docs.photoroom.com/image-editing-api-plus-plan/ai-relight), which can alter colors * [AI Text Removal](https://docs.photoroom.com/image-editing-api-plus-plan/ai-text-removal), which removes text from the main subject * [AI Uncrop](https://docs.photoroom.com/image-editing-api-plus-plan/ai-uncrop) and [AI Expand](https://docs.photoroom.com/image-editing-api-plus-plan/ai-expand), which generates the missing part of the original image * [AI Beautifier](https://docs.photoroom.com/image-editing-api-plus-plan/ai-beautifier), which creates a re-imagined version of the main subject * [AI Upscale](https://docs.photoroom.com/image-editing-api-plus-plan/preview-ai-upscale), which increases the resolution of the original image * [Describe Any Change](https://docs.photoroom.com/image-editing-api-plus-plan/edit-with-ai), which edits the original image using an AI model If you use one of these features and product accuracy is important for you, then we recommend that you have a human validation of the images produced by the API.