{ "openapi": "3.0.3", "info": { "title": "Adobe FireflyPhotoshop API", "description": "This is the comprehensive API reference for Adobe Firefly's Photoshop API suite of services, including all available Photoshop endpoints, request formats, parameters, authentication requirements, and example responses to use when integrating with Firefly's services.\n\n---\n\n### Deprecation notice\n\nPhotoshop API v1 is scheduled for end of life in August 2026; migrate to Photoshop API v2 before then to avoid service disruptions. For official dates, FAQs, and migration resources, see the [Deprecation announcement](https://developer.adobe.com/firefly-services/docs/photoshop/getting-started/deprecation-announcement/).", "version": "1.0" }, "servers": [ { "url": "https://image.adobe.io", "description": "Adobe Photoshop Production", "variables": {} } ], "security": [ { "AccessToken": [], "X-Api-Key": [] } ], "tags": [ { "name": "Masking", "description": "Operations for creating and manipulating masks" }, { "name": "Get status", "description": "Utility endpoints for checking job status and system health" } ], "paths": { "/v1/mask-objects": { "post": { "tags": [ "Masking" ], "operationId": "maskObjects", "summary": "Generate object and background masks", "description": "Given an image, this API generates semantic masks for the foreground objects and a list of background masks that segment the background elements of the image. Each mask includes a label and a URL for the mask image. To check the status of this process, utilize the `Get Status - V1` endpoint.", "x-ffs-async-job": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaskObjectsRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLinkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobError" } } } } } } }, "/v1/mask-body-parts": { "post": { "tags": [ "Masking" ], "operationId": "maskBodyParts", "summary": "Generate human item masks", "description": "This endpoint processes an input image of a human, then identifies and creates masks for various items and sections on the body including sunglasses, hats, upper body apparel, lower body apparel, arms, legs, shoes, and more. The API returns an array of masks corresponding to each detected item and body part.\n\n**Granular Labels (New \u2014 GA):** Set `useGranularLabels: true` in the request body to receive side-specific masks for bilateral body parts. For example, instead of a single combined mask, the API returns separate masks for `Left Shoe` and `Right Shoe`, `Left Arm` and `Right Arm`, and so on. This capability is essential for workflows that apply independent effects \u2014 such as ground shadows or reflections \u2014 to individual limbs at scale.\n\nTo check the status of this process, utilize the `Get Status - V1` endpoint.", "x-ffs-async-job": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaskBodyPartsRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLinkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobError" } } } } } } }, "/v1/refine-mask": { "post": { "tags": [ "Masking" ], "operationId": "refineMask", "summary": "Refine mask", "description": "This endpoint allows you to refine and improve the quality of existing masks. The API will enhance the edges and details of the provided masks to create more precise and accurate results. To check the status of this process, utilize the `Get Status - V1` endpoint.", "x-ffs-async-job": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefineMaskRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLinkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobError" } } } } } } }, "/v1/fill-masked-areas": { "post": { "tags": [ "Masking" ], "operationId": "fillMaskedAreas", "summary": "Fill masked areas", "description": "This endpoint allows you to inpaint masked areas within an image. The API will remove the objects represented by these masks and inpaint the specified areas. Provide a list of masks corresponding to the regions you wish to modify. To check the status of this process, utilize the `Get Status - V1` endpoint.", "x-ffs-async-job": true, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillMaskedAreasRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobLinkResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "404": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputValidationError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobError" } } } } } } }, "/v1/status/{jobId}": { "get": { "tags": [ "Get status", "Masking" ], "operationId": "getJobStatus", "summary": "Get status - v1", "description": "This endpoint allows you to check the status of an asynchronous job for a masking operation. The schema of a 200 response varies depending on the status of the job. A job with a `succeeded` status will include the results in the response and the result objects vary depending on the operation.", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "description": "The schema of a 200 response varies depending on the status of the job. A job with a `succeeded` status will include the results in the response. Result objects vary depending on the operation.", "oneOf": [ { "$ref": "#/components/schemas/JobStatusNotStarted" }, { "$ref": "#/components/schemas/JobStatusRunning" }, { "$ref": "#/components/schemas/JobStatusSucceeded" }, { "$ref": "#/components/schemas/JobStatusFailed" } ], "discriminator": { "propertyName": "status", "mapping": { "not_started": "#/components/schemas/JobStatusNotStarted", "running": "#/components/schemas/JobStatusRunning", "succeeded": "#/components/schemas/JobStatusSucceeded", "failed": "#/components/schemas/JobStatusFailed" } } }, "examples": { "not_started": { "summary": "Job has not started", "value": { "jobId": "12345678-1234-1234-1234-123456789012", "status": "not_started" } }, "running": { "summary": "Job is running", "value": { "jobId": "12345678-1234-1234-1234-123456789012", "status": "running" } }, "succeeded": { "summary": "Job completed successfully", "value": { "jobId": "12345678-1234-1234-1234-123456789012", "status": "succeeded", "semanticMasks": [ { "mediaType": "image/png", "destination": { "url": "https://example.com/semantic-mask-1.png" }, "label": "person", "boundingBox": { "x": 100, "y": 150, "width": 200, "height": 300 }, "score": 0.95 }, { "mediaType": "image/png", "destination": { "url": "https://example.com/semantic-mask-2.png" }, "label": "car", "boundingBox": { "x": 400, "y": 200, "width": 150, "height": 100 }, "score": 0.87 } ], "backgroundMasks": [ { "mediaType": "image/png", "destination": { "url": "https://example.com/background-mask-1.png" }, "label": "sky", "boundingBox": { "x": 0, "y": 0, "width": 800, "height": 200 }, "score": 0.92 }, { "mediaType": "image/png", "destination": { "url": "https://example.com/background-mask-2.png" }, "label": "road", "boundingBox": { "x": 0, "y": 400, "width": 800, "height": 200 }, "score": 0.89 } ] } }, "failed": { "summary": "Job failed", "value": { "jobId": "12345678-1234-1234-1234-123456789012", "status": "failed", "error_code": "processing_error", "message": "Failed to process image due to invalid format" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobError" } } } } } } } }, "components": { "schemas": { "JobError": { "title": "JobError", "type": "object", "properties": { "type": { "type": "string", "description": "The error type." }, "code": { "type": "string", "description": "The error code." }, "title": { "type": "string", "description": "The error description." }, "error_code": { "type": "string", "description": "The internal error code." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetails" }, "description": "The details of the error returned." } }, "description": "Any errors reported in the requested output." }, "InputValidationError": { "title": "InputValidationError", "type": "object", "properties": { "type": { "type": "string", "description": "The error type." }, "code": { "type": "string", "description": "The error code." }, "title": { "type": "string", "description": "The error description." }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/InputValidationErrorDetail" }, "description": "The details of the error returned." } }, "description": "Any errors reported in the requested output." }, "InputValidationErrorDetail": { "title": "InputValidationErrorDetail", "type": "object", "properties": { "allowedValues": { "type": "string", "description": "The name of the input parameter.", "default": "adobe, external, dropbox, azure" }, "reason": { "type": "string", "description": "The reason for the error." } }, "description": "Details of the input validation error returned." }, "ErrorDetails": { "title": "ErrorDetails", "description": "Error details.", "type": "object", "properties": { "name": { "type": "string", "description": "The parameter name." }, "reason": { "type": "string", "description": "The error." } } }, "UrlResource": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the resource. Only these listed domains are accepted in the request: \n
amazonaws.comwindows.netdropboxusercontent.comassets.frame.iostorage.googleapis.com