{ "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 " } }, "required": [ "url" ] }, "JobLinkResponse": { "type": "object", "properties": { "jobId": { "type": "string", "description": "The job ID for the asynchronous job." }, "statusUrl": { "type": "string", "description": "The URL to check the status of the asynchronous job." } }, "required": [ "jobId", "statusUrl" ] }, "FillMaskedAreasInputImage": { "type": "object", "properties": { "source": { "description": "The source of the input image. Dimensions of the image should not be greater than (4000px X 4000px).", "allOf": [ { "$ref": "#/components/schemas/UrlResource" } ] } }, "required": [ "source" ] }, "FillMaskedAreasRequest": { "type": "object", "properties": { "image": { "description": "The image to be processed.", "allOf": [ { "$ref": "#/components/schemas/FillMaskedAreasInputImage" } ] }, "masks": { "description": "The areas of the image represented by this list of masks will be inpainted.", "type": "array", "items": { "$ref": "#/components/schemas/FillMaskedAreasInputImage" } } }, "required": [ "image", "masks" ] }, "MaskBodyPartsInputImage": { "type": "object", "properties": { "source": { "description": "The source of the input image. Dimensions of the image should not be greater than (4000px X 4000px).", "allOf": [ { "$ref": "#/components/schemas/UrlResource" } ] } }, "required": [ "source" ] }, "MaskBodyPartsInputMask": { "type": "object", "properties": { "source": { "description": "The URL of the mask. Dimensions of the mask should not be greater than (4000px X 4000px).", "allOf": [ { "$ref": "#/components/schemas/UrlResource" } ] } }, "required": [ "source" ] }, "MaskBodyPartsRequest": { "type": "object", "properties": { "image": { "description": "The input image.", "allOf": [ { "$ref": "#/components/schemas/MaskBodyPartsInputImage" } ] }, "mask": { "description": "The mask of the subject in the input image.", "allOf": [ { "$ref": "#/components/schemas/MaskBodyPartsInputMask" } ] }, "useGranularLabels": { "type": "boolean", "description": "When set to true, the API returns granular side-specific labels for bilateral body parts (e.g., Left Shoe, Right Shoe, Left Arm, Right Arm). When false or omitted, the API returns the default combined label set. See the Granular Labels section of the documentation for the full label reference.", "default": false } }, "required": [ "image", "mask" ] }, "MaskObjectsInputImage": { "type": "object", "properties": { "source": { "description": "The source of the input image. Dimensions of the image should not be greater than (4000px X 4000px).", "allOf": [ { "$ref": "#/components/schemas/UrlResource" } ] } }, "required": [ "source" ] }, "MaskObjectsRequest": { "type": "object", "properties": { "image": { "description": "The input image.", "allOf": [ { "$ref": "#/components/schemas/MaskObjectsInputImage" } ] } }, "required": [ "image" ] }, "RefineMaskInputImage": { "type": "object", "properties": { "source": { "description": "The source of the input image. Dimensions of the image should not be greater than (4000px X 4000px).", "allOf": [ { "$ref": "#/components/schemas/UrlResource" } ] } }, "required": [ "source" ] }, "RefineMaskRequest": { "type": "object", "properties": { "image": { "description": "The input image.", "allOf": [ { "$ref": "#/components/schemas/RefineMaskInputImage" } ] }, "mask": { "description": "The mask in the input image that needs to be refined.", "allOf": [ { "$ref": "#/components/schemas/RefineMaskInputImage" } ] }, "colorDecontamination": { "type": "boolean", "description": "When `true`, this returns an RGBA image where the masked area has been further refined with color decontamination. A `false` value (default) means that the output will simply be the refined mask.", "default": false } }, "required": [ "image", "mask" ] }, "JobStatusRunning": { "type": "object", "description": "Response when a job is currently being processed. The job has started but is not yet complete.", "properties": { "jobId": { "type": "string", "description": "The job ID." }, "status": { "type": "string", "description": "The status of the job.", "enum": [ "running" ] } }, "required": [ "jobId", "status" ] }, "JobStatusSucceeded": { "type": "object", "description": "Response when a job has completed successfully. In addition to the jobId and status, the response includes the results of the job which vary depending on the operation.", "properties": { "jobId": { "type": "string", "description": "The job ID." }, "status": { "type": "string", "description": "The status of the job.", "enum": [ "succeeded" ] } }, "required": [ "jobId", "status" ] }, "JobStatusFailed": { "type": "object", "description": "Response when a job has failed during processing. Contains error details explaining what went wrong.", "properties": { "jobId": { "type": "string", "description": "The job ID." }, "status": { "type": "string", "description": "The status of the job.", "enum": [ "failed" ] }, "error_code": { "type": "string", "description": "The error code." }, "message": { "type": "string", "description": "The error message." } }, "required": [ "jobId", "status", "error_code", "message" ] }, "JobStatusNotStarted": { "type": "object", "description": "Response when a job has been created but processing has not yet begun. This status indicates the job is queued and waiting to start.", "properties": { "jobId": { "type": "string", "description": "The job ID." }, "status": { "type": "string", "description": "The status of the job.", "enum": [ "not_started" ] } }, "required": [ "jobId", "status" ] } }, "headers": { "X-Access-Consumption-Status": { "description": "This is the value of different consumption statuses based on credits remaining from the user. Possible values can be quota_available, quota_warning_hard_cap, quota_exhausted_using_daily_credits.", "schema": { "type": "string", "enum": [ "quota_available", "quota_warning_hard_cap", "quota_exhausted_using_daily_credits" ] } }, "X-Access-Applied-Until-Date": { "description": "This is the date when credits will be refilled and will be returned as it is from the access profile response. Only available when consumption status is quota_warning_hard_cap, quota_exhausted_using_daily_credits and quota_exhausted.", "schema": { "type": "string", "format": "date-time" } }, "X-Access-Error": { "description": "Represents the reason of authorization failure. This will be a unique string in snake case. Possible values: quota_exhausted, user_profile_denied, user_not_entitled, user_blocked_by_admin, invalid_subscription, user_blocked_due_to_violation, invalid_ims_scope. This will not be available in case of geo IP blocking failure or User Profile region failure from Floodgate.", "schema": { "type": "string", "enum": [ "quota_exhausted", "user_profile_denied", "user_not_entitled", "user_blocked_by_admin", "invalid_subscription", "user_blocked_due_to_violation", "invalid_ims_scope" ] } }, "X-Access-Rate-Limit-Level": { "description": "This is only applicable for third party clients hitting rate limits. This header indicates the level at which the rate limit was applied. Possible values are: org (The rate limit was applied to the entire org), account (The rate limit was applied to the particular tech account of an org).", "schema": { "type": "string", "enum": [ "org", "account" ] } } }, "securitySchemes": { "AccessToken": { "type": "http", "scheme": "bearer", "description": "The Adobe-generated access token, S2S format." }, "X-Api-Key": { "type": "apiKey", "name": "x-api-key", "in": "header", "description": "The client ID for authentication." } } } }