Adobe Photoshop API

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. --- ### Deprecation notice Photos

GitHub OpenAPI

Operations 5

POST /v1/mask-objects Generate object and background masks #
POST /v1/mask-body-parts Generate human item masks #
POST /v1/refine-mask Refine mask #
POST /v1/fill-masked-areas Fill masked areas #
GET /v1/status/{jobId} Get status - v1 #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/adobe:adobe-photoshop-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

adobe-photoshop-openapi.yml Raw ↑
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.


    ---


    ### Deprecation notice


    Photoshop 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.


        **Granular Labels (New — 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 — such as ground shadows or reflections — to individual limbs at scale.


        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/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  <ul><li><code>amazonaws.com</code></li><li><code>windows.net</code></li><li><code>dropboxusercontent.com</code></li><li><code>assets.frame.io</code></li><li><code>storage.googleapis.com</code></li></ul>"
      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.