Adobe Photoshop API v1 to v2 migration - LLM reference guide

Purpose: This document serves as a comprehensive reference for AI assistants (LLMs) helping developers migrate from Adobe Photoshop API v1 to v2. It consolidates patterns, examples, and troubleshooting guidance from all migration guides.

Table of contents

1. Quick reference and decision trees
2. Core architectural changes
3. Migration patterns by operation type
4. Storage solutions reference
5. Output types migration
6. ICC profile support (V2 new feature)
7. Common migration issues and solutions
8. Code transformation examples
9. Validation checklist

Quick reference and decision trees

Complete V1 to V2 endpoint mapping

Decision tree for migration path selection

START: What are you trying to do?
│
├─ Apply image adjustments (autoTone, exposure, etc.)?
│  └─> Use /v2/edit endpoint
│     └─> Guide: Edit Operations Migration
│
├─ Convert PSD to JPEG/PNG/TIFF without edits?
│  └─> Use /v2/create-composite (no edits block)
│     └─> Guide: Format Conversion Migration
│
├─ Using sensei PSDC engine for PSD/Cloud PSD conversion?
│  └─> Use /v2/create-composite
│     └─> URNs map to creativeCloudFileId, paths to creativeCloudPath
│     └─> Guide: Format Conversion Migration (PSDC Engine section)
│
├─ Create a new blank document?
│  └─> Use /v2/create-composite with document params
│     └─> Guide: Document Creation Migration
│
├─ Resize/crop/trim existing document?
│  └─> Use /v2/create-composite with edits.document
│     └─> Guide: Document Operations Migration
│
├─ Add/edit/delete layers in a PSD?
│  └─> Use /v2/create-composite with edits.layers
│     ├─> Image layers? → Layer Operations: Image
│     ├─> Text layers? → Layer Operations: Text
│     ├─> Adjustment layers? → Layer Operations: Adjustments
│     ├─> Smart objects (via V1 documentOperations)? → Layer Operations: Smart Objects
│     ├─> Smart objects (via V1 /psdService/smartObject)? → convenience-apis/smart-object-replace
│     └─> Move/delete/masks? → Layer Operations: Advanced
│
├─ Execute Photoshop actions or scripts?
│  └─> Use /v2/execute-actions
│     └─> Guide: Actions Migration
│
├─ Edit text layers (V1 /psdService/text endpoint)?
│  └─> Use /v2/execute-actions with ActionJSON or UXP
│     └─> Guide: Text Endpoint Migration Specific (validation checklist section)
│
├─ Create artboards from multiple images?
│  └─> Use /v2/create-artboard
│     └─> Guide: Artboard Migration
│
├─ Get PSD structure and layer information?
│  └─> Use /v2/generate-manifest
│     └─> Guide: Manifest Migration
│
└─ Check job status?
   └─> Use /v2/status/{jobId}
      └─> Guide: Status Migration

Migration path by V1 endpoint

If using Lightroom endpoints:

• /lrService/* → All migrate to /v2/edit
• Combine multiple operations in single request

If using PSD layer operations:

• /pie/psdService/documentOperations → /v2/create-composite with edits.layers
• Check layer type for specific guide

If using dedicated smart object or text endpoints:

• /pie/psdService/smartObject → /v2/create-composite with type: "smart_object_layer"
• /pie/psdService/text → /v2/execute-actions (ActionJSON or UXP)

If using action endpoints:

• All action endpoints → /v2/execute-actions
• Action files now published and customizable

If using format conversion:

• /renditionCreate → /v2/create-composite (no edits)
• Can generate multiple outputs in one request

For a complete behavioral reference:

• v2-whats-new.md — net new V2 capabilities (artboard metadata, smart object extraction, UXP scripts, hosted/embedded storage, ICC profiles, granular protection, scriptOutputPattern, multiple outputs)
• v2-api-catalog.md — per-endpoint behavioral comparison tables and a breaking changes checklist covering all endpoints

Core architectural changes

Breaking changes summary

1. Base URL changes

Action Required: Update all base URL references in your code.

2. Request structure changes

V1 Pattern:

{
  "inputs": [
    {
      "href": "<URL>",
      "storage": "external"
    }
  ],
  "options": { ... },
  "outputs": [
    {
      "href": "<URL>",
      "storage": "external",
      "type": "image/jpeg"
    }
  ]
}

V2 Pattern:

{
  "image": {
    "source": {
      "url": "<URL>"
    }
  },
  "edits": { ... },
  "outputs": [
    {
      "destination": {
        "url": "<URL>"
      },
      "mediaType": "image/jpeg"
    }
  ]
}

Key Changes:

• inputs[0].href → image.source.url
• options → edits
• outputs[].href → outputs[].destination.url
• outputs[].type → outputs[].mediaType
• storage → storageType (and it's now optional for external URLs)

data-variant=info

data-slots=text

3. Storage type specification

V1: Required for all storage types

{
  "storage": "external"
}

V2: Optional for external presigned URLs, required only for Azure and Dropbox

{
  "destination": {
    "url": "<URL>",
    "storageType": "azure"  // Only for Azure/Dropbox
  }
}

When to use storageType in V2:

• REQUIRED: Azure Blob Storage → "storageType": "azure"
• REQUIRED: Dropbox → "storageType": "dropbox"
• NOT REQUIRED: AWS S3, Frame.io, Google Drive, standard HTTPS URLs

4. Authentication (unchanged)

V2 uses the same OAuth Server-to-Server authentication as V1:

curl -X POST 'https://ims-na1.adobelogin.com/ims/token/v3' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d 'scope=openid,AdobeID,read_organizations'

New capabilities in V2

1. Batch operations

V1 Required Multiple Sequential Calls:

# Call 1
POST /lrService/autoTone

# Call 2
POST /lrService/autoStraighten

# Call 3
POST /lrService/edit

V2 Single Call:

{
  "edits": {
    "autoTone": true,
    "autoStraighten": {"enabled": true},
    "light": {"exposure": 0.5}
  }
}

2. Four storage options

1. External Storage - Your presigned URLs (AWS S3, Azure, etc.)
2. Creative Cloud Storage - Direct CC integration
3. Embedded Storage - Inline response (text outputs only)
4. Hosted Storage - Adobe-managed temporary storage

3. Published action files

V1 convenience APIs (productCrop, depthBlur, etc.) used hidden server-side actions. V2 publishes these ActionJSON definitions so you can:

• Examine exact action steps
• Customize for your needs
• Learn from Adobe's implementations
• Create variants

4. Enhanced layer operations

V2 supports comprehensive layer manipulation:

• Add, edit, delete, move layers
• Adjustment layers (brightness, hue/saturation, exposure, color balance)
• Smart objects with transformations
• Resize (width/maxWidth) with linked smart objects
• Text layers with full styling
• Layer masks and groups (add, edit, delete pixel masks)
• Blend modes and opacity

5. Better error handling

{
  "status": "failed",
  "errorDetails": [
    {
      "errorCode": "400401",
      "message": "The value provided is not valid."
    },
    {
      "errorCode": "400420",
      "message": "Required fields missing on the API request."
    }
  ]
}

Migration patterns by operation type

A. Edit operations (Lightroom)

V1 Endpoints Consolidated:

• /lrService/autoTone
• /lrService/autoStraighten
• /lrService/presets
• /lrService/xmp
• /lrService/edit

V2 Endpoint: /v2/edit

Pattern: Multiple sequential V1 calls → Single V2 call

V1 Approach (3 separate calls):

# Step 1
curl -X POST https://image.adobe.io/lrService/autoTone \
  -d '{"inputs": {"href": "<URL>", "storage": "external"}}'

# Step 2
curl -X POST https://image.adobe.io/lrService/autoStraighten \
  -d '{"inputs": {"href": "<URL>", "storage": "external"}}'

# Step 3
curl -X POST https://image.adobe.io/lrService/edit \
  -d '{"inputs": {"href": "<URL>"}, "options": {"Exposure": 1.2}}'

V2 Approach (single call):

curl -X POST https://photoshop-api.adobe.io/v2/edit \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "<SIGNED_GET_URL>"
    }
  },
  "edits": {
    "autoTone": true,
    "autoStraighten": {
      "enabled": true,
      "constrainCrop": true
    },
    "light": {
      "exposure": 1.2,
      "contrast": 10
    },
    "color": {
      "saturation": 15
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "<SIGNED_POST_URL>"
      },
      "mediaType": "image/jpeg"
    }
  ]
}'

Adjustment Categories:

• autoTone (boolean)

• autoStraighten (object with enabled, constrainCrop, uprightMode)

• light (exposure, contrast, highlights, shadows, whites, blacks)

• color (saturation, vibrance, whiteBalance)

• effects (clarity, dehaze, texture, vignette)

• sharpen (object with detail, radius, edgeMasking)

  • detail: integer 0-100 (amount of detail sharpening)
  • radius: number (radius of sharpening effect)
  • edgeMasking: integer 0-100 (masking to edges)

• noiseReduction (luminance, color)

• presets (array of preset sources)

• xmp (XMP source object with optional orientation and masks)

Parameter Name Changes:

• V1: PascalCase (Exposure, Contrast, Sharpness)
• V2: camelCase (exposure, contrast) within category objects
• V1 Sharpness (integer 0-100) → V2 sharpen.detail (integer 0-100)

XMP with masks migration (localized adjustments)

For advanced Camera Raw editing workflows with localized adjustments, masks can be included alongside XMP metadata. These masks are binary files that define selection areas for localized adjustments and are passed as part of the /lrService/xmp endpoint in V1.

V1 Approach (/lrService/xmp):

{
  "inputs": {
    "source": {
      "href": "<IMAGE_URL>",
      "storage": "external"
    }
  },
  "options": {
    "xmp": "<XMP_STRING>",
    "masks": [
      {
        "href": "<MASK_FILE_URL>",
        "storage": "external",
        "digest": "37B3568A954F0C80CA946DA0187FB9E2"
      }
    ]
  },
  "outputs": [...]
}

Note: In V1, masks were provided in options.masks alongside the XMP string at the /lrService/xmp endpoint.

V2 Approach:

{
  "image": {
    "source": {
      "url": "<IMAGE_URL>"
    }
  },
  "edits": {
    "xmp": {
      "source": {
        "url": "<XMP_URL>"
      },
      "masks": [
        {
          "source": {
            "url": "<MASK_FILE_URL>"
          },
          "digest": "37B3568A954F0C80CA946DA0187FB9E2"
        }
      ]
    }
  },
  "outputs": [...]
}

Key Changes:

1. Endpoint Change: /lrService/xmp → /v2/edit
2. Structure Change: options.masks (sibling to xmp) → edits.xmp.masks (nested inside xmp)
3. Mask Source: href + storage → source.url
4. XMP Format: V1 accepted inline XMP string in options.xmp, V2 requires file reference in edits.xmp.source
5. Digest: Remains the same - fingerprint for mask identification
6. Storage Parameter: No longer required for standard URLs (only for Azure/Dropbox)

Multiple Masks Example:

{
  "edits": {
    "xmp": {
      "source": {
        "url": "<XMP_URL>"
      },
      "masks": [
        {
          "source": {
            "url": "<MASK_FILE_1_URL>"
          },
          "digest": "37B3568A954F0C80CA946DA0187FB9E2"
        },
        {
          "source": {
            "url": "<MASK_FILE_2_URL>"
          },
          "digest": "D15158972C7044869B171697AEBAFB0F"
        }
      ]
    }
  }
}

Important Notes:

• Masks are optional and only needed for advanced Camera Raw editing with localized adjustments
• Each mask requires both source (file reference) and digest (fingerprint/identifier)
• Mask files are typically binary .bin files generated by Adobe Camera Raw
• The digest is used to associate mask data with XMP adjustments
• Multiple masks can be provided for complex workflows

Note on /lrService/mask endpoint: The V1 /lrService/mask endpoint is a separate, unrelated feature for AI-based mask generation (selectSubject, selectSky, etc.) and has a different deprecation path. The masks discussed in this section are for localized Camera Raw adjustments passed via the /lrService/xmp endpoint.

XMP with orientation override

V2 allows you to override the image's embedded orientation metadata by specifying an orientation parameter within the xmp object. This is useful for applying rotation or flip transformations as part of your Camera Raw workflow.

V2 Structure:

{
  "edits": {
    "xmp": {
      "source": {
        "url": "<XMP_URL>"
      },
      "orientation": "right_top"
    }
  }
}

Orientation Values (EXIF/TIFF Specification):

Combined with Masks Example:

{
  "edits": {
    "xmp": {
      "source": {
        "url": "<XMP_URL>"
      },
      "orientation": "right_top",
      "masks": [
        {
          "source": {
            "url": "<MASK_FILE_URL>"
          },
          "digest": "37B3568A954F0C80CA946DA0187FB9E2"
        }
      ]
    }
  }
}

Key Points:

• orientation is optional and only overrides embedded orientation when specified
• If not provided, the image's embedded EXIF orientation metadata is used
• Uses descriptive string values (e.g., "right_top") instead of numeric EXIF codes
• Automatically handles width/height swaps for 90°/270° rotations (codes 5-8)
• Can be combined with masks and other XMP adjustments
• V1 did not support orientation override - this is a new V2 capability

B. Composite operations (document/layer)

V1 Endpoints Consolidated:

• /pie/psdService/renditionCreate (format conversion)
• /pie/psdService/documentCreate (new documents)
• /pie/psdService/documentOperations (document and layer ops)

V2 Endpoint: /v2/create-composite

Use Cases:

1. Format Conversion - No edits block, just convert PSD to JPEG/PNG
2. Document Creation - image with dimensions, no source
3. Document Operations - edits.document with resize/crop/trim
4. Layer Operations - edits.layers with add/move/delete/edit

Request Structure Pattern:

{
  "image": {
    "source": {"url": "<URL>"}  // For existing documents
    // OR
    "width": 1920,                // For new documents
    "height": 1080,
    "resolution": {"unit": "density_unit", "value": 72},  // Object format required
    "fill": "white",  // Also: "transparent", "background_color" (NOT "backgroundColor" — camelCase is rejected in V2)
                      // Or object: {"solidColor": {"red": 255, "green": 255, "blue": 255}}
    "mode": "rgb",    // Use "grayscale" (not "gray") for grayscale documents
    "depth": 8        // Integer, not string. Valid values depend on mode:
                      // bitmap: 1; grayscale/rgb/hsb: 8, 16, 32; cmyk/lab/multichannel: 8, 16; indexed/duotone: 8
  },
  "edits": {
    "document": {
      "resize": {...},
      "crop": {...},
      "trim": {...}
    },
    "layers": [
      {
        "type": "layer|text_layer|adjustment_layer|smart_object_layer|solid_color_layer",
        "name": "Layer Name",
        "operation": {
          "type": "add|edit|delete",
          "placement": {...}
        },
        // Layer-specific properties
      }
    ]
  },
  "outputs": [...]
}

Layer Operation Types:

• "type": "add" - Add new layer
• "type": "edit" - Edit existing layer properties (required — the operation field is mandatory for edit operations; it cannot be inferred)
• "type": "delete" - Remove layer
• "type": "move" - Move layer to a new position

data-variant=info

data-slots=text

Layer Types:

• "layer" - Image/pixel layers
• "text_layer" - Text layers
• "adjustment_layer" - Non-destructive adjustments
• "smart_object_layer" - Smart objects
• "solid_color_layer" - Solid color fill layers
• "group_layer" - Layer groups (V1 "layerSection" → V2 "group_layer"). Creating a new document with a group layer is not yet supported (upcoming feature). Editing an existing document to add a layer inside a group layer is supported: use placement type: "into" with referenceLayer (e.g. "referenceLayer": { "name": "Group 1" }). The children array is not accepted in edit operations — use into placement with referenceLayer instead.
• "background_layer" - Background layer (V1 "backgroundLayer" → V2 "background_layer"). Target by name: "Background" or the id returned from the manifest (not -1 as in V1; flat backgrounds with no layers use id: 0). Supports add, edit, delete, and convert-to-layer. Move is not supported. Restricted fields: transform, transformMode, pixelMask, protection, blendOptions. To apply any restricted field, convert to a regular layer first (convertToLayer: true). See Background Layer Specifics below.

Placement Options:

{
  "placement": {
    "type": "top"  // or "bottom", "above", "below", "into"
    // For relative placement:
    "referenceLayer": {
      "name": "Layer Name"  // or "id": 123
    }
  }
}

data-variant=warning

data-slots=text

Layer Property Locations (V2):

data-variant=info

data-slots=text

Layer Transforms (V1 → V2):

• V1: layer-level bounds: {left, top, width, height}
• V2: transformMode: "custom" (required) + transform: {offset: {horizontal, vertical}, dimension: {width, height}}
• Additional V2 transform fields: angle (rotation in degrees), skew: {horizontal, vertical}, anchor: {horizontal, vertical}
• transformMode values: "none", "custom", "fit", "fill" — not applicable to adjustment layers

Layer Alignment (V1 → V2):

• V1: layer-level horizontalAlign, verticalAlign
• V2: placement-level horizontalAlignment, verticalAlignment within placement: {type: "custom", horizontalAlignment: "center", verticalAlignment: "center"} (add/move operations only)

Smart Object Specifics:

• Layer type: V1 "smartObject" → V2 "smart_object_layer"
• Source: V1 input: {href, storage} → V2 smartObject.smartObjectFile.source.url (nested deeper)
• Linked flag: V1 smartObject.linked → V2 smartObject.isLinked
• V2 adds SVG and AI as new source formats; V1 supported PSD, JPEG, PNG, and PDF
• Supported source file types: PSD (image/vnd.adobe.photoshop), JPEG (image/jpeg), PNG (image/png), TIFF (image/tiff), SVG (image/svg+xml), AI (application/illustrator), PDF (application/pdf)
• AI file requirement: AI files are only supported when the Create PDF Compatible File option was enabled when saving from Adobe Illustrator.
• Resize with linked smart objects: Width-only resize (no layer edits) → ALL linked SOs are rasterized to pixel layers. Edit/add a linked SO in the same request + resize → that edited SO stays linked; all other linked SOs are rasterized.
• Cannot replace a linked SO with an embedded SO (V2 limitation)

Adjustment Layer Specifics:

• Layer type: V1 "adjustmentLayer" → V2 "adjustment_layer"

• adjustments.type discriminant is required in V2 and did not exist in V1 — omitting it causes the request to be rejected

  Table
  V1 implicit key	V2 adjustments.type	Payload key
  brightnessContrast	"brightness_contrast"	brightnessContrast
  exposure	"exposure"	exposure
  hueSaturation	"hue_saturation"	hueSaturation
  colorBalance	"color_balance"	colorBalance
  (not in V1)	"curves"	—
  (not in V1)	"levels"	—
  (not in V1)	"gradient_map_custom_stops"	—

• Exposure payload rename: Inside the exposure payload, the amount field is exposure in V1 → exposureValue in V2 (range: -20 to 20)

• Hue/Saturation restructure: V1 hueSaturation.channels[] with channel: "master" → V2 hueSaturation.hueSaturationAdjustments[]; omit localRange for master (entire image); include localRange with channelId for specific color range (REDS, YELLOWS, GREENS, CYANS, BLUES, MAGENTAS) — only when colorize: false

• transformMode is not applicable to adjustment layers

• Parameter ranges: brightnessContrast.brightness/contrast (-150 to 150); exposureValue (-20 to 20), offset (-0.5 to 0.5), gammaCorrection (0.01 to 9.99); hue (-180 to 180, or 0–360 when colorize: true); saturation/lightness (-100 to 100, or 0–100 when colorize: true); color balance levels (-100 to 100)

Text Layer Specifics:

• Layer type: V1 "textLayer" → V2 "text_layer"

• Character style range semantics (breaking off-by-one):

  • V1: to = length — {from: 0, to: 5} = 5 characters (indices 0–4)
  • V2: apply.to = inclusive end index — {apply: {from: 0, to: 4}} = indices 0–4 (same result)
  • Migration rule: subtract 1 from V1's to value. Same applies to paragraph style ranges.
  • characterStyles with no range (implicit full-string in V1): If a V1 characterStyle has no from/to fields (applied to entire content implicitly), apply is optional in V2. Omitting apply applies the style to the entire text content. You may include apply: {from: 0, to: len(text.content) - 1} explicitly, but it is not required.

• Character style structure: V1 direct properties → V2 wrapped in characterStyle object

• Font name: V1 top-level fontName → V2 characterStyle.font.postScriptName (inside characterStyle.font)

• Text bounds: V1 layer-level bounds: {left, top, width, height} → V2 text.frame: {type: "area", bounds: {top, left, right, bottom}} where right = left + width, bottom = top + height

• V2 also supports point frames: text.frame: {type: "point", origin: {x, y}}

• V1 text.type: "point" with layer-level bounds: Map bounds.left/bounds.top to text.frame: {type: "point", origin: {x: bounds.left, y: bounds.top}}. Do NOT use transform/transformMode — that rescales glyphs instead of positioning them.

• Default when no frame given: V1 default = area frame at (0,0,4,4); V2 default = point frame at canvas center — always set text.frame explicitly for predictable placement

• textOrientation is a text-level property (not per character-style as V1's orientation)

• Multi-line text: use \r for line breaks (same in both)

• Font options: V1 options.fonts (href+storage) → V2 fontOptions.additionalFonts (source.url); V1 options.globalFont → V2 fontOptions.defaultFontPostScriptName; V1 options.manageMissingFonts: "useDefault" → V2 fontOptions.missingFontStrategy: "use_default" ("fail" unchanged)

Background Layer Specifics:

• Layer type: V1 "backgroundLayer" → V2 "background_layer"
• V1 referenced background by id: -1; V2 returns the actual PIE layer ID from the manifest. For documents with only a flat background (no other layers), the manifest returns id: 0.
• Target background layer in V2 by name: "Background" or by the id from the manifest response.
• Manifest response includes background.canConvertToLayer (boolean) — indicates whether the background can be promoted to a regular layer via convertToLayer: true.
• Placement: Background layers are always at the bottom of the stack. Do NOT include placement on a background_layer add operation — it is ignored.

Allowed direct edits (no conversion needed):

• isVisible — toggle layer visibility
• image.source — replace background pixel content (same image block as other layer types)

Restricted fields — return error when set directly on background_layer: transform, transformMode, pixelMask, protection, blendOptions

Mutually exclusive within a single entry: image (pixel replacement) and convertToLayer: true cannot appear in the same layer entry. Use two separate entries in the layers array (see chained workflow below).

Convert to regular layer: Use convertToLayer: true to promote the background to a regular layer. Use convertedLayerName to assign a name immediately — subsequent layers entries in the same API call can then target it by that name:

{
  "type": "background_layer",
  "name": "Background",
  "operation": { "type": "edit" },
  "convertToLayer": true,
  "convertedLayerName": "Converted Background"
}

After conversion the layer appears in the manifest with type: "layer" and the assigned name. All previously-restricted operations (transform, protection, blendOptions, etc.) are now valid.

Chained workflow — pixel replace + convert + transform in one API call:

Place multiple entries in the layers array; the processor applies them sequentially:

"layers": [
  {
    "type": "background_layer",
    "name": "Background",
    "operation": { "type": "edit" },
    "image": { "source": { "url": "<NEW_BACKGROUND_IMAGE>" } }
  },
  {
    "type": "background_layer",
    "name": "Background",
    "operation": { "type": "edit" },
    "convertToLayer": true,
    "convertedLayerName": "Converted Background"
  },
  {
    "type": "layer",
    "name": "Converted Background",
    "operation": { "type": "edit" },
    "transformMode": "custom",
    "transform": { "angle": 15.0, "skew": { "horizontal": 0.0, "vertical": 0.0 } }
  }
]

Entry 1 replaces the background pixels. Entry 2 converts the background to a named regular layer. Entry 3 applies a transform to the converted layer — using name: "Converted Background" which was assigned in entry 2.

V1 → V2 background layer migration checklist:

• Change type: "backgroundLayer" → type: "background_layer"
• Change id: -1 → use id from manifest (or name: "Background")
• Change visible → isVisible
• Remove locked / protection from background_layer entries (add after conversion)
• Replace add: {} → operation: { "type": "add" } (no placement)
• Replace edit: {} → operation: { "type": "edit" }
• Replace input.href → image.source.url
• To apply transform, protection, or blendOptions: add convertToLayer: true + convertedLayerName, then target the converted layer by name in a subsequent entry

C. Actions migration

V1 Endpoints Consolidated:

• /pie/psdService/photoshopActions
• /pie/psdService/actionJSON
• /pie/psdService/productCrop
• /pie/psdService/depthBlur
• /pie/psdService/splitView
• /pie/psdService/sideBySide

V2 Endpoint: /v2/execute-actions

Key Change: Action files for convenience APIs are now published!

Pattern for .atn Files:

V1:

{
  "options": {
    "actions": [
      {"href": "<ACTION_URL>", "storage": "external"}
    ]
  }
}

V2:

{
  "options": {
    "actions": [
      {
        "source": {
          "url": "<ACTION_URL>"
        }
      }
    ]
  }
}

Pattern for Inline ActionJSON:

V1:

{
  "options": {
    "actionJSON": [
      {"_obj": "convertMode", "to": {...}}
    ]
  }
}

V2:

{
  "options": {
    "actions": [
      {
        "source": {
          "content": "[{\"_obj\":\"convertMode\",\"to\":{...}}]",
          "contentType": "application/json"
        }
      }
    ]
  }
}

Important: ActionJSON must be stringified JSON in V2.

Multiple Actions: V2 supports up to 10 actions executed in sequence:

{
  "options": {
    "actions": [
      {"source": {"url": "<ACTION_1_URL>"}},
      {"source": {"url": "<ACTION_2_URL>"}},
      {"source": {"url": "<ACTION_3_URL>"}}
    ]
  }
}

Additional Resources:

{
  "options": {
    "actions": [...],
    "additionalContents": [  // Max 25 (images/compositing resources)
      {"source": {"url": "<IMAGE_URL>"}}
    ],
    "brushes": [           // Max 10 — must use external URLs (binary, no inline)
      {"source": {"url": "<BRUSH_URL>"}}
    ],
    "patterns": [          // Max 10 — must use external URLs (binary, no inline)
      {"source": {"url": "<PATTERN_URL>"}}
    ],
    "fontOptions": {
      "additionalFonts": [ // Max 10 — must use external URLs (binary, no inline)
        {"source": {"url": "<FONT_URL>"}}
      ],
      "missingFontStrategy": "use_default"
    }
  }
}

Additional Contents Placeholder: Reference in ActionJSON or UXP scripts as __ADDITIONAL_CONTENT_0__, __ADDITIONAL_CONTENT_1__, etc. (0-based index matches position in additionalContents array). Binary resources (brushes, patterns, fonts) must use external URLs — inline content is not supported for these types.

Convenience API details

Product Crop:

• Steps: 8 action steps
• Additional Images: No
• Key Parameter: Padding (default: 50 pixels, customizable)
• What It Does: Auto cutout + trim + padding + flatten
• Customization: Modify canvasSize step (5th action) to change padding values
• Use Case: E-commerce product isolation with consistent padding

Depth Blur: Depth Blur is not yet supported in V2. Neural Filters are unavailable in V2; continue using the V1 /pie/psdService/depthBlur endpoint for this feature. The parameters below are for reference only.

• Steps: 1 action step (Neural Gallery Filter)

• Additional Images: No

• Key Parameters: 11 customizable parameters (all have defaults)

  • spl::focalSelector: "auto" - Focus point selection
  • spl::selectSubjectUsage: 1 - Subject selection mode
  • spl::slideAperture: 50 - Blur strength (0-100)
  • spl::slideFocalDist: 50 - Focal distance (0-100)
  • spl::slideFocalRange: 50 - Focal range size (0-100)
  • spl::sliderBrightness: 0 - Brightness (-100 to 100)
  • spl::sliderHaze: 0 - Haze effect (-100 to 100)
  • spl::sliderNoise: 0 - Grain/noise (0-100)
  • spl::sliderSaturation: 0 - Saturation (-100 to 100)
  • spl::sliderTint: 0 - Color tint (-100 to 100)
  • spl::sliderWarmness: 0 - Color temperature (-100 to 100)

• What It Does: Applies neural depth-of-field blur effect

• Use Case: Portrait and product photography with bokeh effects

Text Layer Operations:

• V1: /pie/psdService/text — declarative request with options.layers[] (layer name + characterStyles with size, color, fontPostScriptName, etc.)
• V2: /v2/execute-actions — no equivalent declarative text endpoint exists in V2; must use ActionJSON or UXP
• Additional Contents: No

When to use ActionJSON vs UXP for text edits:

ActionJSON pattern (stringified, passed as options.actions[].source.content with contentType: "application/json"):

1. select layer by _name → makeVisible: true
2. set textStyle: font size (size with _unit: "pointsUnit", textOverrideFeatureName: 808465458, typeStyleOperationType: 3)
3. set textStyle: font (fontPostScriptName, fontName, fontStyleName)
4. set textStyle: color (color with _obj: "RGBColor", red, green, blue)

For multiple layers: repeat the select + set sequence within the same stringified ActionJSON array.

UXP pattern (passed as options.uxp.source.content with contentType: "application/javascript"):

• Use core.executeAsModal() for document modifications
• Access layer.kind === "text" to identify text layers
• Use layer.textItem.characterStyle to modify fauxBold, fauxItalic, etc.
• Use plugin-temp:/filename.ext for script output files

Split View:

• Steps: 34 action steps

• Additional Contents: Yes (2 required)

  • __ADDITIONAL_CONTENT_0__: Edited/final output image
  • __ADDITIONAL_CONTENT_1__: Product logo

• Key Parameters: Width: 1200px (resizes final output)

• What It Does: Masked before/after comparison with center divider line + logo

• Use Case: Demonstrating image processing effects with branding

Side by Side:

• Steps: 19 action steps

• Additional Contents: Yes (2 required)

  • __ADDITIONAL_CONTENT_0__: Edited/final output image
  • __ADDITIONAL_CONTENT_1__: Product logo

• Key Parameters: Width: 1195.0px (exact value with decimal)

• What It Does: Simple side-by-side comparison without masking + logo

• Use Case: Clean before/after comparisons with branding

• Key Difference from Split View: Simpler, no complex masking or divider lines

UXP Scripts (Limited Availability):

{
  "options": {
    "uxp": {
      "source": {
        "content": "const app = require('photoshop').app; app.activeDocument.flatten();",
        "contentType": "application/javascript"
      }
    }
  }
}

Use plugin-temp:/filename.ext path in UXP scripts to write output files to the plugin temporary directory (e.g., plugin-temp:/result.json). Then reference them in scriptOutputPattern.

Script Output Discovery:

{
  "outputs": [
    {
      "destination": {"validityPeriod": 3600},
      "mediaType": "application/json",
      "scriptOutputPattern": "result.json"
    }
  ]
}

Supports glob patterns: *.json, result-*.png, etc.

D. Other operations

Artboards:

• V1: image.adobe.io/pie/psdService/artboardCreate → V2: photoshop-api.adobe.io/v2/create-artboard
• Input structure: V1 inputs[].href → V2 images[].source.url (or creativeCloudPath, creativeCloudFileId, lightroomPath). V1 inputs[].storage → only needed for Azure/Dropbox in outputs; omit for standard URLs.
• Output structure: Same as other endpoints — outputs[].href → outputs[].destination.url, outputs[].type → outputs[].mediaType.
• New V2 parameter: artboardSpacing (optional integer, pixels, default 50) — horizontal spacing between artboards.
• Validation: 1–25 images, 1–25 outputs.
• Source options: External URL, Creative Cloud Path, Creative Cloud File ID, Lightroom Path.
• Output formats: JPEG, PNG, TIFF, PSD, PSDC, JSON manifest (6 formats).
• Storage options: Same as other endpoints (External, Hosted, Embedded, Creative Cloud, Azure, Dropbox).

Manifest:

• V1: /pie/psdService/documentManifest
• V2: /v2/generate-manifest
• Pattern: Returns manifest to specified output destination
• Options: includeLayerThumbnails, includeXmp, maximumThumbnailDepth, trimToTransparency (boolean, crops layer thumbnails to visible content; requires includeLayerThumbnails: true; has no effect on adjustment layers or layers with no pixel data — those always return a blank white canvas thumbnail; specific to /v2/generate-manifest — for trimming exported images in /v2/create-composite or /v2/execute-actions, use cropMode: "trim_to_transparency" in output options instead)
• V1 manifest had locked (boolean) on layers → V2 returns protection (array of flags: none, all, transparency, composite, position, artboard_autonest)
• V1 manifest had mask property with offset.x/offset.y → V2 uses pixelMask with offset.horizontal/offset.vertical, plus new read-only fields hasMask, extendOpaque, bounds, and editable fields enabled (boolean, default true, toggles mask visibility without deleting data) and linked (boolean, default true, whether mask transforms with the layer); density/feather moved to separate userMask property: density (integer, 0–100, mask opacity/strength) and feather (number, 0–250, edge softness in pixels); to delete a pixel mask in edit operations use pixelMask: { "delete": true } (edit only, not valid on add; supported on all layer types)
• Clipping mask: V1 mask.clip → V2 layerSettings.clippingMask in manifest; use top-level isClipped: true in edit operations
• Layer type renames (manifest response only — V2 edit/create-composite request payloads still use "type": "layer" unchanged): layer→pixel_layer, textLayer→text_layer, layerSection→group_layer, layerSection(artboard)→artboard, smartObject→smart_object_layer, fillLayer→solid_color_layer, adjustmentLayer→adjustment_layer, backgroundLayer→background_layer
• bounds format changed: V1 {height, left, top, width} → V2 {left, top, right, bottom} (no height/width; compute from right-left, bottom-top)
• thumbnail changed: V1 plain string URL → V2 object {mediaType, url} (only present when thumbnails requested)
• Artboard children key changed: V1/groups use children[]; V2 artboards use layers[] for their children (recursive traversal must handle both)
• Document field renames: bitDepth→depth, iccProfileName→iccProfile, name→title, height+width→bounds; photoshopBuild removed
• See manifest-response-migration.md for the full field-by-field response format reference

Status:

• V1: Service-specific endpoints
• V2: Unified /v2/status/{jobId}
• Same jobId works across all operation types

E. Export layers (single vs multi-layer)

Export layers via outputs[].layers on the /v2/create-composite endpoint. Behavior differs between single-layer and multi-layer exports.

Single-Layer Export — specify exactly one layer in outputs[].layers:

• Supports all cropMode values: "layer_bounds" (default), "trim_to_transparency", "document_bounds"
• Supported formats: JPEG, PNG, TIFF, PSD (PSD is allowed for single-layer only)
• Default JPEG quality: photoshop_max; default PNG compression: default (level 6)

Multi-Layer Export — specify two or more layers in outputs[].layers:

• Composites those layers to a single raster file
• Supported formats: JPEG, PNG, TIFF — PSD is NOT supported for multi-layer export
• cropMode supports "document_bounds" (default) and "trim_to_transparency" — "layer_bounds" returns a validation error
• Same quality/compression defaults as single-layer

Document Export — no layers specified (exports full document):

• cropMode supports "document_bounds" (default) and "trim_to_transparency" — "layer_bounds" returns a validation error

// Single-layer: V2 example with cropMode
{
  "image": {"source": {"url": "<PSD_URL>"}},
  "outputs": [{
    "destination": {"url": "<OUTPUT_URL>"},
    "mediaType": "image/png",
    "layers": [{"id": 1096}],
    "cropMode": "trim_to_transparency"
  }]
}

// Multi-layer: V2 example with cropMode (no PSD)
{
  "image": {"source": {"url": "<PSD_URL>"}},
  "outputs": [{
    "destination": {"url": "<OUTPUT_URL>"},
    "mediaType": "image/jpeg",
    "layers": [{"id": 1096}, {"id": 996}],
    "quality": "maximum",
    "cropMode": "trim_to_transparency"
  }]
}

Layer identifier: mutually exclusive. Each entry in outputs[].layers[] must use either id or name — not both. V1 tolerated both fields together as disambiguation hints; V2 rejects the payload with: "Each layer reference must contain exactly one of id or name (not both)." Prefer id when present; drop name.

V1 outputs[].layers[] with visible field: Some V1 renditionCreate/documentOperations payloads included outputs[].layers[] entries with {id, visible: true} to select which layers appear in the composite export. Map these to V2 outputs[].layers[] as [{id: N}, ...] — this triggers multi-layer composite export. Do not move them to edits.layers[] (that path requires type + operation and performs layer edits, not export selection).

Storage solutions reference

Storage decision matrix

1. External storage (presigned URLs)

Supports: AWS S3, Azure Blob, Dropbox, Frame.io, Google Drive

For Input:

{
  "image": {
    "source": {
      "url": "<PRESIGNED_GET_URL>"
    }
  }
}

For Output:

{
  "outputs": [
    {
      "destination": {
        "url": "<PRESIGNED_PUT_URL>",
        "storageType": "azure"  // Only for Azure or Dropbox
      },
      "mediaType": "image/jpeg"
    }
  ]
}

When to use storageType:

• Azure: "storageType": "azure"
• Dropbox: "storageType": "dropbox"
• AWS S3, Frame.io, Google Drive: NOT required

2. Creative Cloud storage

Note: Creative Cloud Storage refers specifically to ACP (Adobe Content Platform) for file storage and access.

{
  "image": {
    "source": {
      "creativeCloudPath": "my-folder/input.psd"
      // OR
      "creativeCloudFileId": "urn:aaid:...",
      "creativeCloudProjectId": "urn:aaid:sc:..."  // Optional
    }
  },
  "outputs": [
    {
      "destination": {
        "creativeCloudPath": "my-folder/output.jpg"
      },
      "mediaType": "image/jpeg"
    }
  ]
}

data-variant=warning

data-slots=text

When to use:

• Integration with CC ecosystem and ACP
• Direct access to user's CC files stored in ACP
• Collaboration workflows

3. Embedded storage

For text-based outputs only (XMP, JSON):

{
  "outputs": [
    {
      "destination": {
        "embedded": "string"  // For XMP (XML text)
        // OR
        "embedded": "json"    // For JSON manifests
        // OR
        "embedded": "base64"  // For small binary data
      },
      "mediaType": "application/rdf+xml"  // or application/json
    }
  ]
}

When to use:

• XMP metadata extraction
• JSON manifest data
• Immediate access needed
• No storage setup required

IMPORTANT: Do NOT use for images. Only for text/metadata outputs.

Response format:

{
  "result": {
    "outputs": [
      {
        "destination": {
          "embedded": "string",
          "content": "<?xml version=\"1.0\"...>"  // For string
          // OR for JSON:
          // "embedded": "json",
          // "content": {"document": {...}}
        },
        "mediaType": "application/rdf+xml"
      }
    ]
  }
}

4. Hosted storage

Adobe-managed temporary storage:

{
  "outputs": [
    {
      "destination": {
        "validityPeriod": 3600  // Seconds: 60-86400 (max 1 day)
      },
      "mediaType": "image/jpeg"
    }
  ]
}

When to use:

• Temporary processing workflows
• No long-term storage needed (files expire within 24 hours)
• Quick prototyping

Response:

{
  "result": {
    "outputs": [
      {
        "destination": {
          "url": "https://adobe-hosted-storage.../file.jpg?expires=..."
        },
        "mediaType": "image/jpeg"
      }
    ]
  }
}

IMPORTANT: Download before URL expires (maximum 24 hours from job completion)!

Output types migration

Overview

V2 introduces significant changes to output format specifications affecting all endpoints that generate outputs. This section covers the structural changes and format-specific parameter transformations for JPEG, PNG, PSD, and TIFF outputs.

Structural changes (all output formats)

All output types share these common structural changes:

*storageType is optional and only required for Azure Blob Storage and Dropbox.

V1 Pattern:

{
  "outputs": [{
    "href": "https://...",
    "storage": "external",
    "type": "image/jpeg"
  }]
}

V2 Pattern:

{
  "outputs": [{
    "destination": {
      "url": "https://..."
    },
    "mediaType": "image/jpeg"
  }]
}

JPEG quality migration

V1: Numeric values (1-7 or 1-12) V2: Descriptive string enums

JPEG quality mapping

Default: Use "photoshop_max" for production workflows.

V1 implicit quality: When a V1 execute-actions or actionJSON payload omits the quality field entirely, V1 uses its highest-quality JPEG encoder setting. Always set quality: "photoshop_max" in V2 when migrating from a V1 payload with no quality field — omitting it in V2 may default to a lower level and produce pixel-level differences against V1 reference outputs.

execute-actions pixel fidelity: V1 and V2 use different JPEG encoders. Even with identical quality settings, sub-1% pixel differences are expected. Use "photoshop_max" as the baseline when pixel fidelity is critical; accept sub-1% diffs as normal for JPEG across API versions.

V1 Example:

{
  "type": "image/jpeg",
  "quality": 7,
  "width": 2000
}

V2 Example:

{
  "mediaType": "image/jpeg",
  "quality": "maximum",
  "width": 2000
}

PNG compression migration

V1: Three compression levels: "small", "medium", "large" V2: Ten granular compression levels (zlib/libpng standard)

PNG compression mapping

V2 PNG compression values (complete)

• "none" (level 0) - No compression
• "very_low" (level 1) - Minimal compression
• "low" (level 2) - Low compression
• "medium_low" (level 3) - Medium-low compression
• "medium" (level 4) - Medium compression
• "medium_high" (level 5) - Medium-high compression
• "default" (level 6) - Library standard (default when omitted)
• "high" (level 7) - High compression
• "very_high" (level 8) - Very high compression
• "maximum" (level 9) - Maximum compression

V1 Example:

{
  "type": "image/png",
  "compression": "medium"
}

V2 Example:

{
  "mediaType": "image/png",
  "compression": "medium"
}

Important: PNG uses compression, NOT quality.

PSD and TIFF outputs

PSD and TIFF outputs have no format-specific parameters (no quality or compression options in V2). Only the structural field changes apply:

V1 PSD:

{
  "href": "https://...",
  "storage": "external",
  "type": "image/vnd.adobe.photoshop"
}

V2 PSD:

{
  "destination": {
    "url": "https://..."
  },
  "mediaType": "image/vnd.adobe.photoshop"
}

Cloud PSD (PSDC): Use "mediaType": "document/vnd.adobe.cpsd+dcxucf" (primary form). Both document/vnd.adobe.cpsd+dcxucf and document/vnd.adobe.cpsd+dcx are supported for ACP (Adobe Cloud Platform) storage and external storage. The older V1 form image/vnd.adobe.photoshop+dcx is not used in V2.

Common output fields

All output types support these optional fields:

• width (integer, ≥ 0) - Output width in pixels
• height (integer, ≥ 0) - Output height in pixels
• maxWidth (integer, ≥ 0) - Maximum width in pixels
• resample (string, optional) - Resampling algorithm when resizing to width/maxWidth. Values: nearest_neighbor, bilinear, bicubic, bicubic_smoother, bicubic_sharper. Defaults to bicubic_sharper. Applies to JPEG, PNG, and TIFF exports.
• shouldTrimToCanvas (boolean) - Trim transparent pixels

Multiple outputs

V2 supports up to 25 outputs per request:

{
  "outputs": [
    {
      "destination": {"url": "..."},
      "mediaType": "image/jpeg",
      "quality": "maximum",
      "width": 2400
    },
    {
      "destination": {"url": "..."},
      "mediaType": "image/jpeg",
      "quality": "medium",
      "width": 800
    },
    {
      "destination": {"url": "..."},
      "mediaType": "image/png",
      "compression": "high"
    }
  ]
}

Color mode and bit depth validation

The API automatically converts source images when the color mode or bit depth is not supported by the target format. The behavior differs by export path.

data-variant=info

data-slots=text

Bit depth validation table

data-variant=info

data-slots=text

Color mode validation table

Output type-specific issues

Issue: Numeric JPEG quality

Problem:

{
  "mediaType": "image/jpeg",
  "quality": 7
}

Error:

Invalid value '7' at path 'outputs[0].quality'.
Accepted values are: very_poor, poor, low, medium, high, maximum, photoshop_max

Solution:

{
  "mediaType": "image/jpeg",
  "quality": "maximum"
}

Issue: Old PNG compression values

Problem:

{
  "mediaType": "image/png",
  "compression": "small"
}

Error:

Invalid value 'small' at path 'outputs[0].compression'.

Solution:

{
  "mediaType": "image/png",
  "compression": "maximum"
}

Issue: Using quality for PNG

Problem:

{
  "mediaType": "image/png",
  "quality": "high"
}

Error:

'quality' parameter is not supported for PNG format

Solution:

{
  "mediaType": "image/png",
  "compression": "high"
}

ICC profile support (V2 new feature)

ICC profile support is a new V2 capability — V1 had no output color profile configuration.

Overview

ICC profiles can be applied in two places:

1. On outputs — controls the exported file's color space. Add iccProfile to any output in /v2/create-composite, /v2/create-artboard, or /v2/execute-actions. Supported for JPEG, PNG, TIFF, and PSD — not for PSDC (Cloud PSD).
2. On image (document creation) — sets the document's embedded color profile at creation time. Add iccProfile to the image block when creating a new document (no image.source). Supports both standard and custom profiles.

Standard profiles

Use a predefined profile name (no external file needed):

"iccProfile": {
  "type": "standard",
  "name": "sRGB IEC61966-2.1",
  "imageMode": "rgb"
}

RGB profiles: "Adobe RGB (1998)", "Apple RGB", "ColorMatch RGB", "sRGB IEC61966-2.1"

Grayscale profiles (Dot Gain): "Dot Gain 10%", "Dot Gain 15%", "Dot Gain 20%", "Dot Gain 25%", "Dot Gain 30%"

Grayscale profiles (Gray Gamma): "Gray Gamma 1.8", "Gray Gamma 2.2"

data-variant=warning

data-slots=text

Custom profiles (enables CMYK)

Use your own .icc file — required for CMYK output:

"iccProfile": {
  "type": "custom",
  "name": "U.S. Web Coated (SWOP) v2",
  "imageMode": "cmyk",
  "source": {
    "url": "https://example.com/profiles/custom.icc"
  }
}

imageMode options for custom: "rgb", "grayscale", or "cmyk".

Format support table

Conversion behavior with ICC profile

When an ICC profile is specified on a full-document export, format-specific bit-depth/color-mode conversion is skipped — the ICC transformation handles color management instead. See Color Mode and Bit Depth Validation tables above.

Output migration quick reference

For LLMs helping with migration:

1. Always check output format before suggesting parameters:

   • JPEG → use quality (string enum)
   • PNG → use compression (string enum)
   • PSD/TIFF → no format-specific parameters

2. Default recommendations:

   • JPEG: "photoshop_max" (highest quality, recommended default)
   • PNG: "default" (level 6 library standard; default when omitted)

3. Common transformation pattern:

   // V1 to V2 transformation
   v1.outputs[0].href → v2.outputs[0].destination.url
   v1.outputs[0].type → v2.outputs[0].mediaType
   v1.outputs[0].quality (7) → v2.outputs[0].quality ("maximum")
   v1.outputs[0].storage → omit (for S3) or move to destination.storageType
   

Common migration issues and solutions

Category: Missing/incorrect fields

Issue: Missing outputs array

Problem:

{
  "image": {"source": {"url": "<URL>"}},
  "edits": {...}
  // Missing outputs!
}

Solution:

{
  "image": {"source": {"url": "<URL>"}},
  "edits": {...},
  "outputs": [
    {
      "destination": {"url": "<OUTPUT_URL>"},
      "mediaType": "image/jpeg"
    }
  ]
}

Issue: Unencoded characters in source/destination URLs

Problem: V1 was lenient with URL encoding; V2 validates URLs strictly across all endpoints.

{"image": {"source": {"url": "https://host/My Folder/file.psd"}}}

Solution: Percent-encode all special characters in every source.url and destination.url field.

{"image": {"source": {"url": "https://host/My%20Folder/file.psd"}}}

Spaces (%20) are the most common culprit. Error returned: "The url is malformed or blocked". Applies to all V2 endpoints.

Issue: String values for numeric fields (strict type coercion)

Problem: V1 accepted strings for numeric fields; V2 enforces strict types.

{"image": {"width": "1920", "height": "1080", "depth": "8"}}

Solution: Use integers/floats.

{"image": {"width": 1920, "height": 1080, "depth": 8}}

Commonly affected: image.width, image.height, image.depth, outputs[].width, outputs[].height, opacity, resolution.value.

Issue: Missing type field on layer in edits.layers[]

Problem: Layer entry has no type field — e.g., a visibility-only edit from V1 where type was inferred.

{"edits": {"layers": [{"name": "My Layer", "isVisible": false}]}}

Solution: type is required on every entry in edits.layers[]. V2 does not infer layer type.

{"edits": {"layers": [{"type": "layer", "name": "My Layer", "isVisible": false}]}}

Use the appropriate type: "layer", "text_layer", "adjustment_layer", "smart_object_layer", "group_layer", or "solid_color_layer".

Issue: Wrong media type property

Problem: Using type instead of mediaType

{
  "outputs": [{
    "destination": {...},
    "type": "image/jpeg"  // Wrong!
  }]
}

Solution:

{
  "outputs": [{
    "destination": {...},
    "mediaType": "image/jpeg"  // Correct!
  }]
}

Issue: Invalid quality values

Problem: Using V1 numeric quality (1-7)

{
  "quality": 7  // V1 format
}

Solution: Use V2 string values

{
  "quality": "maximum"  // V2 format
}

Valid V2 values: "very_poor", "poor", "low", "medium", "high", "maximum", "photoshop_max"

Note: V2 only accepts string enums. Numeric values from V1 are not supported.

Category: Storage issues

Issue: Using V1 storage parameter

Problem:

{
  "storage": "external"  // V1 format
}

Solution: Use destination structure

{
  "destination": {
    "url": "<URL>"
    // storageType only for Azure/Dropbox
  }
}

Issue: storageType confusion

Problem: Adding storageType for AWS S3

{
  "destination": {
    "url": "<S3_URL>",
    "storageType": "external"  // NOT needed!
  }
}

Solution: Omit storageType for standard URLs

{
  "destination": {
    "url": "<S3_URL>"
    // No storageType needed
  }
}

Only use storageType for:

• Azure: "storageType": "azure"
• Dropbox: "storageType": "dropbox"

Issue: Embedded storage for images

Problem: Using embedded for image output

{
  "destination": {
    "embedded": "base64"
  },
  "mediaType": "image/jpeg"  // Too large!
}

Solution: Use external or hosted storage for images

{
  "destination": {
    "url": "<OUTPUT_URL>"
  },
  "mediaType": "image/jpeg"
}

Embedded is only for XMP metadata and JSON manifests.

Category: Request structure issues

Issue: Using V1 input structure

Problem:

{
  "inputs": [
    {
      "href": "<URL>",
      "storage": "external"
    }
  ]
}

Solution: Use V2 image structure

{
  "image": {
    "source": {
      "url": "<URL>"
    }
  }
}

Issue: Wrong parameter names

Problem: Using V1 PascalCase

{
  "options": {
    "Exposure": 1.2,
    "Contrast": 10
  }
}

Solution: Use V2 camelCase with categories

{
  "edits": {
    "light": {
      "exposure": 1.2,
      "contrast": 10
    }
  }
}

Category: Layer operations

Issue: Missing operation type

Problem: Not specifying operation type when adding layer

{
  "edits": {
    "layers": [
      {
        "type": "layer",
        "name": "New Layer",
        "image": {
          "source": {"url": "<URL>"}
        }
        // Missing operation!
      }
    ]
  }
}

Solution: Specify operation type

{
  "edits": {
    "layers": [
      {
        "type": "layer",
        "name": "New Layer",
        "image": {
          "source": {"url": "<URL>"}
        },
        "operation": {
          "type": "add",
          "placement": {"type": "top"}
        }
      }
    ]
  }
}

Issue: Wrong layer type name

Problem: Using V1 layer type names

{
  "type": "textLayer"     // V1
  "type": "adjustmentLayer"  // V1
  "type": "smartObject"   // V1
}

Solution: Use V2 underscore format

{
  "type": "text_layer"           // V2
  "type": "adjustment_layer"     // V2
  "type": "smart_object_layer"   // V2
  "type": "solid_color_layer"    // V2
}

Issue: Incorrect placement syntax

Problem: Using V1 placement syntax

{
  "add": {
    "insertTop": true
  }
}

Solution: Use V2 operation structure

{
  "operation": {
    "type": "add",
    "placement": {
      "type": "top"
    }
  }
}

Category: XMP and masks issues

Issue: V1 mask structure not working

Problem: Using V1 mask structure with href and storage

{
  "edits": {
    "xmp": {
      "source": {"url": "<XMP_URL>"}
    },
    "masks": [
      {
        "href": "<MASK_URL>",
        "storage": "external",
        "digest": "37B3568A954F0C80CA946DA0187FB9E2"
      }
    ]
  }
}

Solution: Masks must be nested inside xmp object, not sibling to it, and use source structure

{
  "edits": {
    "xmp": {
      "source": {"url": "<XMP_URL>"},
      "masks": [
        {
          "source": {
            "url": "<MASK_URL>"
          },
          "digest": "37B3568A954F0C80CA946DA0187FB9E2"
        }
      ]
    }
  }
}

Issue: Inline XMP string not supported in V2

Problem: Using inline XMP string from V1

{
  "edits": {
    "xmp": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
  }
}

Solution: V2 requires XMP to be provided as a file reference

{
  "edits": {
    "xmp": {
      "source": {
        "url": "<XMP_FILE_URL>"
      }
    }
  }
}

Or use Creative Cloud storage:

{
  "edits": {
    "xmp": {
      "source": {
        "creativeCloudPath": "/path/to/metadata.xmp"
      }
    }
  }
}

Issue: Missing mask digest

Problem: Providing mask without digest

{
  "masks": [
    {
      "source": {"url": "<MASK_URL>"}
    }
  ]
}

Solution: Each mask must include a digest for identification

{
  "masks": [
    {
      "source": {"url": "<MASK_URL>"},
      "digest": "37B3568A954F0C80CA946DA0187FB9E2"
    }
  ]
}

Issue: Using numeric orientation values

Problem: Using numeric EXIF codes for orientation

{
  "edits": {
    "xmp": {
      "source": {"url": "<XMP_URL>"},
      "orientation": 6
    }
  }
}

Solution: Use descriptive string values from the enum

{
  "edits": {
    "xmp": {
      "source": {"url": "<XMP_URL>"},
      "orientation": "right_top"
    }
  }
}

Valid orientation values: "top_left", "top_right", "bottom_right", "bottom_left", "left_top", "right_top", "right_bottom", "left_bottom"

Issue: Orientation at wrong nesting level

Problem: Placing orientation at edits level instead of within xmp

{
  "edits": {
    "xmp": {
      "source": {"url": "<XMP_URL>"}
    },
    "orientation": "right_top"
  }
}

Solution: Nest orientation inside the xmp object

{
  "edits": {
    "xmp": {
      "source": {"url": "<XMP_URL>"},
      "orientation": "right_top"
    }
  }
}

Category: Actions issues

Issue: Wrong ActionJSON format

Problem: Providing ActionJSON as object/array

{
  "source": {
    "content": [{"_obj": "..."}],  // Wrong: array
    "contentType": "application/json"
  }
}

Solution: Stringify the ActionJSON

{
  "source": {
    "content": "[{\"_obj\":\"...\"}]",  // Correct: string
    "contentType": "application/json"
  }
}

Issue: Missing contentType

Problem:

{
  "source": {
    "content": "[...]"
    // Missing contentType!
  }
}

Solution: Always specify contentType for inline content

{
  "source": {
    "content": "[...]",
    "contentType": "application/json"
  }
}

Issue: Wrong action structure

Problem: Using V1 action structure

{
  "options": {
    "actions": [
      {
        "href": "<URL>",
        "storage": "external"
      }
    ]
  }
}

Solution: Use V2 source structure

{
  "options": {
    "actions": [
      {
        "source": {
          "url": "<URL>"
        }
      }
    ]
  }
}

Category: Artboard issues

Issue: Incorrect input structure

Problem: Using v1 input format

{
  "inputs": [
    {"href": "<URL>", "storage": "external"}
  ]
}

Solution: Use v2 images structure

{
  "images": [
    {"source": {"url": "<URL>"}}
  ]
}

Issue: Too many images

Problem: Exceeding the maximum number of images (25).

Error: Array size must be between 1 and 25 at path 'images'

Solution: Ensure between 1 and 25 images in the request.

Issue: Too many outputs

Problem: Exceeding the maximum number of outputs (25).

Error: Array size must be between 1 and 25 at path 'outputs'

Solution: Ensure between 1 and 25 outputs in the request.

Issue: Missing required source

Problem: Missing source in image.

Error: Required field 'source' is missing at path 'images[0]'

Solution: Every image must have a source field.

{
  "images": [
    {"source": {"url": "<URL>"}}
  ]
}

Issue: Invalid hosted storage period

Problem: Hosted storage validityPeriod outside allowed range (60–86400 seconds).

Error: validityPeriod must be between 60 and 86400 seconds

Solution: Use a value between 60 (1 minute) and 86400 (24 hours).

{
  "destination": {"validityPeriod": 3600}
}

Issue: Missing storage type for Azure/Dropbox

Problem: Using Azure or Dropbox without specifying storageType.

Error: Azure Blob Storage URL requires 'storageType': 'azure'

Solution: Add storageType for Azure and Dropbox.

{
  "destination": {
    "url": "<AZURE_URL>",
    "storageType": "azure"
  }
}

Issue: Invalid JPEG quality value (artboard outputs)

Problem: Using numeric quality instead of string enum.

Error: Invalid value '7' at path 'outputs[0].quality'. Accepted values are: very_poor, poor, low, medium, high, maximum, photoshop_max

Solution: Use string enum values for quality.

{
  "mediaType": "image/jpeg",
  "quality": "maximum"
}

Category: Response handling

Issue: Looking for manifest in initial response

Problem: Expecting manifest data immediately

Solution: Poll status endpoint

# Step 1: Submit job
curl -X POST https://photoshop-api.adobe.io/v2/generate-manifest ...

# Response: {"jobId": "..."}

# Step 2: Poll status
curl -X GET https://photoshop-api.adobe.io/v2/status/{jobId} ...

# Response when complete:
# {
#   "status": "succeeded",
#   "result": {
#     "outputs": [
#       {"url": "..."}  // for hosted/url destinations
#       // OR
#       {"destination": {"embedded": "...", "content": {...}}}  // for embedded
#     ]
#   }
# }

Issue: Not handling all status values

Problem: Only checking succeeded/failed

if (status === 'succeeded') { ... }
else { /* assume failed */ }

Solution: Handle all status values

switch (status) {
  case 'succeeded':
    // Process result
    break;
  case 'failed':
    // Handle error
    break;
  case 'pending':
  case 'running':
    // Continue polling
    break;
  default:
    // Unknown status
}

Issue: Not handling error details array

Problem: Expecting single error message

console.error(status.error);  // Wrong

Solution: Iterate error details array

status.errorDetails.forEach(error => {
  console.error(`${error.errorCode}: ${error.message}`);
});

Code transformation examples

Example 1: Simple edit (auto tone)

V1 Code:

curl -X POST https://image.adobe.io/lrService/autoTone \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "href": "https://my-storage.com/input.jpg",
    "storage": "external"
  },
  "outputs": [
    {
      "href": "https://my-storage.com/output.jpg",
      "storage": "external",
      "type": "image/jpeg"
    }
  ]
}'

V2 Code:

curl -X POST https://photoshop-api.adobe.io/v2/edit \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "https://my-storage.com/input.jpg"
    }
  },
  "edits": {
    "autoTone": true
  },
  "outputs": [
    {
      "destination": {
        "url": "https://my-storage.com/output.jpg"
      },
      "mediaType": "image/jpeg"
    }
  ]
}'

Key Transformations:

1. Base URL: image.adobe.io → photoshop-api.adobe.io
2. Endpoint: /lrService/autoTone → /v2/edit
3. Input: inputs.href → image.source.url
4. Operation: Implicit → edits.autoTone: true
5. Output: outputs[].href → outputs[].destination.url
6. Type: type → mediaType
7. Storage: Removed (not needed for standard URLs)

Example 2: Complex edit (multiple adjustments)

V1 Code (3 separate calls):

# Call 1
curl -X POST https://image.adobe.io/lrService/autoTone ...

# Call 2
curl -X POST https://image.adobe.io/lrService/autoStraighten ...

# Call 3
curl -X POST https://image.adobe.io/lrService/edit \
  -d '{
    "inputs": {...},
    "options": {
      "Exposure": 1.2,
      "Contrast": 10,
      "Saturation": 15
    },
    "outputs": [...]
  }'

V2 Code (single call):

curl -X POST https://photoshop-api.adobe.io/v2/edit \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "<INPUT_URL>"
    }
  },
  "edits": {
    "autoTone": true,
    "autoStraighten": {
      "enabled": true,
      "constrainCrop": true
    },
    "light": {
      "exposure": 1.2,
      "contrast": 10
    },
    "color": {
      "saturation": 15
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "<OUTPUT_URL>"
      },
      "mediaType": "image/jpeg"
    }
  ]
}'

Key Transformations:

1. Three calls → One call
2. Operations combined in edits object
3. PascalCase params → camelCase within categories
4. Exposure → light.exposure
5. Saturation → color.saturation

Example 3: Format conversion (PSD to JPEG)

V1 Code:

curl -X POST https://image.adobe.io/pie/psdService/renditionCreate \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": [
    {
      "href": "https://my-storage.com/document.psd",
      "storage": "external"
    }
  ],
  "outputs": [
    {
      "href": "https://my-storage.com/output.jpg",
      "storage": "external",
      "type": "image/jpeg",
      "quality": 7,
      "width": 1920
    }
  ]
}'

V2 Code:

curl -X POST https://photoshop-api.adobe.io/v2/create-composite \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "https://my-storage.com/document.psd"
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "https://my-storage.com/output.jpg"
      },
      "mediaType": "image/jpeg",
      "quality": "maximum",
      "width": 1920
    }
  ]
}'

Key Transformations:

1. Endpoint: /pie/psdService/renditionCreate → /v2/create-composite
2. Input: inputs[0].href → image.source.url
3. Output: outputs[0].href → outputs[0].destination.url
4. Quality: Numeric 7 → String "maximum"
5. Storage: Removed (not needed)
6. No edits block (just format conversion)

Example 4: Layer addition

V1 Code:

curl -X POST https://image.adobe.io/pie/psdService/documentOperations \
  -d '{
  "inputs": [{
    "href": "<DOCUMENT_URL>",
    "storage": "external"
  }],
  "options": {
    "layers": [
      {
        "type": "layer",
        "name": "New Image",
        "add": {
          "insertTop": true
        },
        "input": {
          "href": "<IMAGE_URL>",
          "storage": "external"
        }
      }
    ]
  },
  "outputs": [{
    "href": "<OUTPUT_URL>",
    "storage": "external",
    "type": "image/vnd.adobe.photoshop"
  }]
}'

V2 Code:

curl -X POST https://photoshop-api.adobe.io/v2/create-composite \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "<DOCUMENT_URL>"
    }
  },
  "edits": {
    "layers": [
      {
        "type": "layer",
        "name": "New Image",
        "image": {
          "source": {
            "url": "<IMAGE_URL>"
          }
        },
        "operation": {
          "type": "add",
          "placement": {
            "type": "top"
          }
        }
      }
    ]
  },
  "outputs": [
    {
      "destination": {
        "url": "<OUTPUT_URL>"
      },
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}'

Key Transformations:

1. Endpoint: /documentOperations → /create-composite
2. Structure: options.layers → edits.layers
3. Add operation: add: {insertTop: true} → operation: {type: "add", placement: {type: "top"}}
4. Layer source: input.href → image.source.url

Example 4b: Layer edit operation

V1 Code (with edit: {}):

curl -X POST https://image.adobe.io/pie/psdService/documentOperations \
  -d '{
  "inputs": [{
    "href": "<DOCUMENT_URL>",
    "storage": "external"
  }],
  "options": {
    "layers": [
      {
        "id": 123,
        "type": "layer",
        "edit": {},
        "text": {
          "content": "Updated text"
        }
      }
    ]
  },
  "outputs": [{
    "href": "<OUTPUT_URL>",
    "storage": "external",
    "type": "image/vnd.adobe.photoshop"
  }]
}'

V2 Code (explicit edit operation):

curl -X POST https://photoshop-api.adobe.io/v2/create-composite \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "<DOCUMENT_URL>"
    }
  },
  "edits": {
    "layers": [
      {
        "id": 123,
        "type": "text_layer",
        "text": {
          "content": "Updated text"
        },
        "operation": {
          "type": "edit"
        }
      }
    ]
  },
  "outputs": [
    {
      "destination": {
        "url": "<OUTPUT_URL>"
      },
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}'

Key Transformations:

1. Layer type: type: "layer" → type: "text_layer" (specify actual layer type)
2. Operation: V1 "edit": {} → V2 "operation": {"type": "edit"}
3. Edit operation is now explicit and required (not implicit)
4. When V1 layer has "edit": {} with no add/delete, use edit operation in V2

Example 5: Action execution

V1 Code:

curl -X POST https://image.adobe.io/pie/psdService/photoshopActions \
  -d '{
  "inputs": [{
    "href": "<IMAGE_URL>",
    "storage": "external"
  }],
  "options": {
    "actions": [
      {
        "href": "<ACTION_FILE_URL>",
        "storage": "external"
      }
    ]
  },
  "outputs": [{
    "href": "<OUTPUT_URL>",
    "storage": "external",
    "type": "image/vnd.adobe.photoshop"
  }]
}'

V2 Code:

curl -X POST https://photoshop-api.adobe.io/v2/execute-actions \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "<IMAGE_URL>"
    }
  },
  "options": {
    "actions": [
      {
        "source": {
          "url": "<ACTION_FILE_URL>"
        }
      }
    ]
  },
  "outputs": [
    {
      "destination": {
        "url": "<OUTPUT_URL>"
      },
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}'

Key Transformations:

1. Endpoint: /photoshopActions → /execute-actions
2. Input: inputs[0].href → image.source.url
3. Action: actions[0].href → actions[0].source.url
4. Storage: Removed from action and input

Example 6: Status checking

V1 Code:

# Lightroom job
curl -X GET https://image.adobe.io/lrService/status/{jobId} \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey"

# Photoshop job
curl -X GET https://image.adobe.io/pie/psdService/status/{jobId} \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey"

V2 Code:

# All jobs use same endpoint
curl -X GET https://photoshop-api.adobe.io/v2/status/{jobId} \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey"

Key Transformations:

1. Service-specific endpoints → Unified endpoint
2. Same jobId works for all operation types

Example 7: Artboard create

V1 Code:

curl -X POST https://image.adobe.io/pie/psdService/artboardCreate \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": [
    {"href": "<IMAGE_1_URL>", "storage": "external"},
    {"href": "<IMAGE_2_URL>", "storage": "external"}
  ],
  "outputs": [
    {
      "href": "<SIGNED_POST_URL>",
      "storage": "external",
      "type": "image/vnd.adobe.photoshop"
    }
  ]
}'

V2 Code:

curl -X POST https://photoshop-api.adobe.io/v2/create-artboard \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "images": [
    {"source": {"url": "<IMAGE_1_URL>"}},
    {"source": {"url": "<IMAGE_2_URL>"}}
  ],
  "outputs": [
    {
      "destination": {"url": "<SIGNED_POST_URL>"},
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}'

Key Transformations:

1. Endpoint: /pie/psdService/artboardCreate → /v2/create-artboard
2. Input: inputs[] → images[]; href + storage → source.url
3. Output: outputs[].href → outputs[].destination.url; type → mediaType
4. Optional: Add artboardSpacing (integer, pixels) for horizontal spacing between artboards (default 50)
5. Storage: Omit for standard URLs; use destination.storageType only for Azure/Dropbox

V2 status response output patterns

Overview

The V2 status response structure varies significantly from V1, particularly in how outputs are represented. Understanding these patterns is crucial for correct migration, as the result.outputs[] field structure depends on the destination type specified in the original request.

Base response structure

All V2 status responses share this base structure regardless of destination type:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "createdTime": "2025-11-11T10:00:00.000Z",
  "modifiedTime": "2025-11-11T10:05:30.000Z",
  "status": "succeeded",
  "result": {
    "outputs": [...]  // Structure varies by destination type
  }
}

Key structural changes from V1

Status Values: "pending", "running", "succeeded", "failed"

Destination type patterns

The result.outputs[] structure varies based on the destination type specified in the request. Here are all 5 destination types and their status response patterns:

1. External URL destination (presigned URLs)

Use Case: AWS S3, Azure Blob, Dropbox, Frame.io, Google Drive presigned URLs

Request:

{
  "outputs": [{
    "destination": {
      "url": "https://s3.amazonaws.com/bucket/output.jpg?X-Amz-Signature=..."
    },
    "mediaType": "image/jpeg",
    "quality": "maximum"
  }]
}

Status Response (succeeded):

{
  "jobId": "...",
  "createdTime": "2025-11-11T10:00:00.000Z",
  "modifiedTime": "2025-11-11T10:05:30.000Z",
  "status": "succeeded",
  "result": {
    "outputs": [{
      "destination": {
        "url": "https://s3.amazonaws.com/bucket/output.jpg?X-Amz-Signature=..."
      },
      "mediaType": "image/jpeg",
      "quality": "maximum"
    }]
  }
}

Pattern: The output echoes back the destination URL exactly as provided. The file has been written to the presigned URL.

V1 vs V2 Comparison:

// V1 Status Response
{
  outputs: [{
    _links: {
      self: { href: "https://s3.amazonaws.com/bucket/output.jpg?..." }
    },
    input: "https://input-url...",
    status: "succeeded"
  }]
}

// V2 Status Response
{
  result: {
    outputs: [{
      destination: { url: "https://s3.amazonaws.com/bucket/output.jpg?..." },
      mediaType: "image/jpeg",
      quality: "maximum"
    }]
  },
  status: "succeeded"  // Job-level, not per-output
}

Key Migration Points:

• V1: outputs[]._links.self.href → V2: result.outputs[].destination.url
• V1: Per-output status → V2: Single job-level status
• V1: Includes input field → V2: No input echo
• V2: Preserves all output parameters (quality, width, height, etc.)

2. Embedded destination (inline content)

Use Case: XMP metadata, JSON manifests, small text outputs returned inline

Request (embedded: "string"):

{
  "outputs": [{
    "destination": {
      "embedded": "string"
    },
    "mediaType": "application/rdf+xml"
  }]
}

Status Response:

{
  "status": "succeeded",
  "result": {
    "outputs": [{
      "destination": {
        "embedded": "string",
        "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<x:xmpmeta xmlns:x=\"adobe:ns:meta/\">...</x:xmpmeta>"
      },
      "mediaType": "application/rdf+xml"
    }]
  }
}

Request (embedded: "json"):

{
  "outputs": [{
    "destination": {
      "embedded": "json"
    },
    "mediaType": "application/json"
  }]
}

Status Response:

{
  "result": {
    "outputs": [{
      "destination": {
        "embedded": "json",
        "content": {
          "document": {
            "width": 1920,
            "height": 1080,
            "layers": [...]
          }
        }
      },
      "mediaType": "application/json"
    }]
  }
}

Request (embedded: "base64"):

{
  "outputs": [{
    "destination": {
      "embedded": "base64"
    },
    "mediaType": "image/png"
  }]
}

Status Response:

{
  "result": {
    "outputs": [{
      "destination": {
        "embedded": "base64",
        "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
      },
      "mediaType": "image/png"
    }]
  }
}

Pattern: Destination includes content field with actual data inline.

Embedded Types:

• "string": Plain text (XMP, XML, text files) - returned as string
• "json": JSON data (manifests, structured data) - returned as parsed JSON object
• "base64": Binary data (small images/files) - returned as base64-encoded string

V1 vs V2:

// V1: Limited embedded support, varied formats
{
  outputs: [{
    _links: { self: { href: "data:..." } },
    status: "succeeded"
  }]
}

// V2: Standardized embedded format with content field
{
  result: {
    outputs: [{
      destination: {
        embedded: "string",
        content: "<?xml version=..."
      },
      mediaType: "application/rdf+xml"
    }]
  }
}

Important Restrictions:

• Only use embedded for text/metadata/small file outputs
• Not suitable for large images (use URL or Hosted instead)
• Recommended for XMP extraction and JSON manifests

3. Hosted destination (Adobe temporary storage)

Use Case: Temporary storage without managing your own presigned URLs (V2 new feature)

Request:

{
  "outputs": [{
    "destination": {
      "validityPeriod": 3600  // seconds: 60-86400 (1 min - 24 hours)
    },
    "mediaType": "image/jpeg",
    "quality": "high"
  }]
}

Status Response:

{
  "status": "succeeded",
  "result": {
    "outputs": [{
      "destination": {
        "url": "https://adobe-hosted-storage.example.com/path/to/output.jpg?expires=1699700000&signature=abc123..."
      },
      "mediaType": "image/jpeg",
      "quality": "high"
    }]
  }
}

Pattern: Adobe generates a temporary presigned URL valid for the specified period (max 24 hours). The URL is returned in destination.url.

Key Characteristics:

• Adobe manages the storage temporarily
• URL includes expiration timestamp and signature
• Files automatically deleted after expiration
• Maximum validity period: 86400 seconds (24 hours)
• Minimum validity period: 60 seconds (1 minute)

CRITICAL: Download the file before the URL expires! No recovery after expiration.

V1 Equivalent: None - this is a new V2 feature.

Use Cases:

• Temporary processing workflows
• Quick prototyping
• No long-term storage needed
• Simplifies workflows by eliminating presigned URL generation

4. Creative Cloud destination

Use Case: Direct integration with Creative Cloud storage (ACP - Adobe Content Platform)

Request:

{
  "outputs": [{
    "destination": {
      "creativeCloudPath": "my-folder/output.jpg"
    },
    "mediaType": "image/jpeg",
    "quality": "maximum"
  }]
}

Status Response:

{
  "status": "succeeded",
  "result": {
    "outputs": [{
      "destination": {
        "creativeCloudPath": "my-folder/output.jpg"
      },
      "mediaType": "image/jpeg",
      "quality": "maximum"
    }]
  }
}

Pattern: The output echoes back the Creative Cloud path. File has been written to CC storage (ACP).

Alternative: Creative Cloud File ID

// Request
{
  "destination": {
    "creativeCloudFileId": "urn:aaid:sc:VA6C2:...",
    "creativeCloudProjectId": "urn:aaid:sc:VA6C2:..."  // Optional
  }
}

// Status Response
{
  "destination": {
    "creativeCloudFileId": "urn:aaid:sc:VA6C2:...",
    "creativeCloudProjectId": "urn:aaid:sc:VA6C2:..."
  }
}

V1 vs V2:

// V1 Status Response (CC storage)
{
  outputs: [{
    _links: {
      self: {
        href: "my-folder/output.jpg",
        storage: "external"
      }
    },
    status: "succeeded"
  }]
}

// V2 Status Response (CC storage)
{
  result: {
    "outputs": [{
      destination: {
        creativeCloudPath: "my-folder/output.jpg"
      },
      mediaType: "image/jpeg"
    }]
  },
  status: "succeeded"
}

When to Use:

• Integration with Creative Cloud ecosystem and ACP
• Direct access to user's CC files
• Collaboration workflows
• Seamless CC workflow integration

5. Script output pattern (dynamic file discovery)

Use Case: UXP scripts that generate files dynamically (V2 new feature, /v2/execute-actions only)

Request with glob pattern:

{
  "outputs": [{
    "destination": {
      "validityPeriod": 3600
    },
    "mediaType": "application/json",
    "scriptOutputPattern": "*.json"  // Matches any JSON files
  }]
}

Status Response when script generates 3 JSON files:

{
  "status": "succeeded",
  "result": {
    "outputs": [
      {
        "destination": {
          "url": "https://adobe-hosted.../fonts.json?expires=..."
        },
        "mediaType": "application/json"
      },
      {
        "destination": {
          "url": "https://adobe-hosted.../layers.json?expires=..."
        },
        "mediaType": "application/json"
      },
      {
        "destination": {
          "url": "https://adobe-hosted.../metadata.json?expires=..."
        },
        "mediaType": "application/json"
      }
    ]
  }
}

Pattern: One request output with pattern expands to multiple status response outputs (one per matched file).

Exact filename match:

{
  "scriptOutputPattern": "document-info.json"  // Exact match
}
// Status: Single output with that specific file

Glob patterns supported:

• *.json - All JSON files generated by script
• result-*.png - Files matching pattern (result-1.png, result-2.png, etc.)
• data-*.txt - Pattern with wildcard
• document-info.json - Exact filename (no glob)

Pattern Expansion Examples:

1 request output → 1 status output (exact match):

// Request
{"scriptOutputPattern": "metadata.json"}

// Status
{"outputs": [{"destination": {"url": ".../metadata.json?..."}}]}

1 request output → 3 status outputs (glob match):

// Request
{"scriptOutputPattern": "*.json"}

// Status (if 3 JSON files generated)
{"outputs": [
  {"destination": {"url": ".../file1.json?..."}},
  {"destination": {"url": ".../file2.json?..."}},
  {"destination": {"url": ".../file3.json?..."}}
]}

Restrictions:

• Only works with Hosted or Embedded destinations
• Cannot use with URL or Creative Cloud destinations (require pre-known filenames)
• Only applicable to /v2/execute-actions endpoint
• Files are filtered by mediaType - only matching extensions included
• Not applicable to /v2/edit, /v2/create-composite, or other endpoints

MediaType Filtering: If mediaType: "application/json", only files with .json extension are included, even if pattern matches others.

V1 Equivalent: None - this is a new V2 feature for UXP script workflows.

Use Cases:

• UXP scripts that generate unknown number of files
• Scripts that output dynamic filenames
• Batch processing where file count varies
• Discovery of script-generated assets

Multiple outputs example

When multiple outputs with different destinations are requested:

Request:

{
  "outputs": [
    {
      "destination": {"url": "https://s3.../output.jpg?..."},
      "mediaType": "image/jpeg",
      "quality": "maximum",
      "width": 2400
    },
    {
      "destination": {"embedded": "json"},
      "mediaType": "application/json"
    },
    {
      "destination": {"creativeCloudPath": "folder/output.png"},
      "mediaType": "image/png",
      "compression": "high"
    },
    {
      "destination": {"validityPeriod": 7200},
      "mediaType": "image/tiff"
    }
  ]
}

Status Response:

{
  "status": "succeeded",
  "result": {
    "outputs": [
      {
        "destination": {"url": "https://s3.../output.jpg?..."},
        "mediaType": "image/jpeg",
        "quality": "maximum",
        "width": 2400
      },
      {
        "destination": {
          "embedded": "json",
          "content": {"document": {"width": 1920, "height": 1080}}
        },
        "mediaType": "application/json"
      },
      {
        "destination": {"creativeCloudPath": "folder/output.png"},
        "mediaType": "image/png",
        "compression": "high"
      },
      {
        "destination": {"url": "https://adobe-hosted.../output.tiff?expires=..."},
        "mediaType": "image/tiff"
      }
    ]
  }
}

Pattern: Each output maintains its destination type and parameters. Outputs array order is preserved.

Failed job response

When job fails, no result field is present:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "createdTime": "2025-11-11T10:00:00.000Z",
  "modifiedTime": "2025-11-11T10:05:35.000Z",
  "status": "failed",
  "errorDetails": [
    {
      "errorCode": "400401",
      "message": "The value provided is not valid."
    },
    {
      "errorCode": "400420",
      "message": "Required fields missing on the API request."
    }
  ]
}

Pattern: Failed jobs have errorDetails array instead of result object.

Pending/running job response

While job is processing, result field may be absent or incomplete:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "createdTime": "2025-11-11T10:00:00.000Z",
  "modifiedTime": "2025-11-11T10:00:15.000Z",
  "status": "running"
}

Pattern: No result field until job completes. Poll endpoint until status is "succeeded" or "failed".

Recommended polling interval: 5 seconds

V1 to V2 status response quick reference table

Key migration insights

1. Response Structure Mirror: In V2, the status response result.outputs[] structure directly mirrors the request outputs[] structure:

• Request fields are echoed back (mediaType, quality, width, etc.)
• Destination details are preserved or enhanced (URL for hosted, content for embedded)
• No additional _links or input fields added

2. Status Location:

• V1: Per-output status (outputs[].status)
• V2: Single job-level status (status at root)

3. Hypermedia Links:

• V1: Extensive _links objects throughout
• V2: No hypermedia links - direct data structures only

4. Destination Determination: The destination type in status response is determined by request:

• Request has url → Response has url (external or hosted-generated)
• Request has embedded → Response has embedded + content
• Request has creativeCloudPath → Response has creativeCloudPath
• Request has scriptOutputPattern + hosted → Response has multiple url entries

5. Output Array Expansion: Only scriptOutputPattern causes output expansion (1 request → N response outputs). All other destination types maintain 1:1 mapping.

Migration validation points

When migrating status polling code:

Update field references:

• data.created → data.createdTime
• data.modified → data.modifiedTime
• data.outputs → data.result.outputs
• data.outputs[0]._links.self.href → data.result.outputs[0].destination.url (or appropriate field)

Update status checking:

• V1: Loop through outputs[] checking each output.status
• V2: Check single status field at root level

Remove hypermedia logic:

• V1: Navigate via _links.self.href
• V2: Access result.outputs[] directly

Handle destination types:

• Check destination.url for external/hosted
• Check destination.content for embedded
• Check destination.creativeCloudPath for CC
• Handle multiple outputs for scriptOutputPattern

Error handling:

• V1: Check outputs[].status for errors
• V2: Check status === "failed" and parse errorDetails[] array

Validation checklist

Use this checklist when migrating or validating V1 → V2 code:

Request structure

• Base URL updated to photoshop-api.adobe.io
• Endpoint path updated (see mapping table)
• inputs[].href changed to image.source.url
• options changed to edits (if applicable)
• outputs array present and properly configured
• outputs[].href changed to outputs[].destination.url
• outputs[].type changed to outputs[].mediaType
• storage parameter removed or changed to storageType (only for Azure/Dropbox)

Edit operations specific

• Multiple V1 calls consolidated into single V2 call
• Parameters moved to category objects (light, color, effects)
• Parameter names changed from PascalCase to camelCase
• autoTone specified as boolean true
• autoStraighten specified as object with enabled: true
• XMP inline string converted to file reference (edits.xmp.source)
• Masks moved from options.masks to edits.xmp.masks
• Mask structure changed from href + storage to source.url
• Each mask includes both source and digest
• XMP orientation (if used) nested inside xmp object, not at edits level
• Orientation uses string values (e.g., "right_top") not numeric codes

Layer operations specific

• Layer type names use underscores (text_layer, adjustment_layer, smart_object_layer, solid_color_layer)
• Group layer type is "group_layer" (not "layer_group" or "layerSection"). Creating a new document with a group layer is not yet supported (upcoming feature); editing an existing document to add a layer inside a group layer is supported (into + referenceLayer).
• Operation type specified (add, edit, delete) — operation field is required for edits, not inferred
• Move operations use operation.type: "move" with placement (not move: {...})
• V1 layers with edit: {} and no add/delete → V2 with operation.type: "edit"
• Placement structure uses operation.placement format
• Relative placement uses referenceLayer (not relativeTo)
• Layer processing order is top-down in V2 (not bottom-up); layers used as referenceLayer must appear earlier in the array
• Layer source uses source not input
• Layer lock uses "protection": ["all"] / ["none"] (not "locked": true/false)
• Clipping mask: use "isClipped": true at layer level (not mask.clip)
• Pixel mask: rename mask → pixelMask; offset uses offset.horizontal/offset.vertical (not offset.x/offset.y)
• Pixel mask delete: use pixelMask: { "delete": true } on edit operations to remove a mask from a layer
• Text layers: characterStyles wrapped in characterStyle object
• Text layers: paragraphStyles wrapped in paragraphStyle object
• Pixel mask offset uses offset.horizontal/offset.vertical (not offset.x/offset.y)
• Pixel mask: V1 mask.linked/enabled/input → V2 pixelMask.linked/enabled/source.url (also: prefix changed from mask to pixelMask)
• Visibility: visible → isVisible
• Opacity/blend mode: for most layer types, top-level opacity and blendMode (not blendOptions); for smart_object_layer, use blendOptions.opacity and blendOptions.blendMode
• Layer transforms: V1 bounds {left,top,width,height} → V2 transform {offset:{horizontal,vertical}, dimension:{width,height}}; transformMode: "custom" is required
• Alignment: V1 layer-level horizontalAlign/verticalAlign → V2 placement-level horizontalAlignment/verticalAlignment within placement: {type: "custom", ...} (add/move only)

Adjustment layer operations specific

• Layer type: "adjustmentLayer" → "adjustment_layer"
• adjustments.type discriminant required in V2 (did not exist in V1): "brightness_contrast", "exposure", "hue_saturation", "color_balance" (also new: "curves", "levels", "gradient_map_custom_stops")
• Inside the exposure payload: field exposure (amount) renamed to exposureValue
• Hue/Sat: V1 channels[] with channel: "master" → V2 hueSaturationAdjustments[]; omit localRange for master; include localRange with channelId for specific color range — only when colorize: false
• transformMode is not applicable to adjustment layers — omit it

Text layer operations specific

• Layer type: "textLayer" → "text_layer"
• Character/paragraph style range: V1 to = length → V2 apply.to = inclusive end index; subtract 1 from V1's to when migrating
• Style properties wrapped in characterStyle object (V2); apply: {from, to} is the range wrapper
• Font name: V1 top-level fontName → V2 characterStyle.font.postScriptName (inside characterStyle.font)
• Paragraph styles wrapped in paragraphStyle object (V2)
• Text bounds: V1 layer-level bounds {left,top,width,height} → V2 text.frame {type:"area", bounds:{top,left,right,bottom}}; right=left+width, bottom=top+height
• Point frames: use text.frame: {type:"point", origin:{x,y}} for single-point text
• V2 default (no frame): point at canvas center — always set text.frame explicitly
• textOrientation is text-level property (not per character-style)
• Font options: options.fonts (href+storage) → fontOptions.additionalFonts (source.url); options.globalFont → fontOptions.defaultFontPostScriptName; manageMissingFonts:"useDefault" → missingFontStrategy:"use_default"

Smart object layer operations specific

• Layer type: "smartObject" → "smart_object_layer"
• Source: V1 input: {href, storage} → V2 smartObject.smartObjectFile.source.url
• Linked flag: smartObject.linked → smartObject.isLinked
• transformMode required when using transform object: "none", "custom", "fit", or "fill"
• V2 adds SVG and AI as new source file types (not in V1); PSD, JPEG, PNG, TIFF, and PDF were already supported in V1
• AI files require Create PDF Compatible File to have been enabled when saving from Illustrator
• Width-only resize: linked SOs are rasterized to pixel layers unless their content is provided in the same request

Text endpoint migration specific (/pie/psdService/text)

• No declarative text endpoint exists in V2 — use /v2/execute-actions
• Choose ActionJSON for fixed edits on known layers; choose UXP for conditional/iterative logic
• ActionJSON must be stringified; include contentType: "application/json"
• UXP: use core.executeAsModal() for document modifications; include contentType: "application/javascript"
• Multi-layer edits: V1 options.layers[] often contains many layers (10–50+). The V2 ActionJSON MUST contain one select+set step pair per layer — do NOT deduplicate layers that share the same text content, and do NOT drop any layers. Select by _id (integer), not _name (layer names are non-unique). Example for a two-layer payload: [{"_obj":"select","_target":[{"_ref":"layer","_id":71}],"makeVisible":false},{"_obj":"set","_target":[{"_ref":"textLayer","_enum":"ordinal","_value":"targetEnum"}],"to":{"_obj":"textLayer","textKey":"Hello"}},{"_obj":"select","_target":[{"_ref":"layer","_id":44}],"makeVisible":false},{"_obj":"set","_target":[{"_ref":"textLayer","_enum":"ordinal","_value":"targetEnum"}],"to":{"_obj":"textLayer","textKey":"World"}}]
• Bounds/visibility-only edits: When the V1 payload only changes layer bounds or visibility (no text content/style fields), V2 still requires a non-empty options with ActionJSON or UXP — an empty options object is rejected with "options: At least one of actions or uxp must be provided". Generate ActionJSON that selects each target layer by _id and applies: translate/transform for bounds changes, hide/show for visibility. Do NOT attempt a declarative V2 text-layer edit without at least one entry in options.actions or options.uxp.
• options.fonts[] → options.fontOptions.additionalFonts[] with {source: {url}} structure
• options.manageMissingFonts: "useDefault" → options.fontOptions.missingFontStrategy: "use_default"

Action operations specific

• Actions use source object not href
• ActionJSON is stringified (not array/object)
• contentType specified for inline content
• Additional contents use correct field name (additionalContents, not additionalImages)
• Additional contents placeholder format is __ADDITIONAL_CONTENT_0__ (not __ADDITIONAL_IMAGES_0__ or __ADDITIONAL_CONTENTS_PATH_0__); preserve the numeric index from the original V1 placeholder exactly — do NOT renumber
• additionalContents max count is 25 (not 10)
• UXP script uses object syntax for options.uxp (not array)
• UXP script output paths use plugin-temp:/filename.ext (not __UXP_OUTPUT_PATH__)
• Script output destination uses {"validityPeriod": 3600} (not {"hosted": true} for scriptOutputPattern)

Artboard operations specific

• inputs[] changed to images[] with source object
• Each image has source with valid reference (url, creativeCloudPath, creativeCloudFileId, or lightroomPath)
• Image count between 1 and 25
• Output count between 1 and 25
• artboardSpacing (if used) is integer in pixels
• Output structure uses destination.url and mediaType (not href/type)

Storage configuration

• Correct storage type for use case selected
• storageType only used for Azure and Dropbox
• Embedded storage only used for XMP/JSON outputs
• Hosted storage has validityPeriod (60-86400 seconds)
• Creative Cloud paths have no leading slash (use "my-folder/file.psd" not "/my-folder/file.psd")

Output configuration

• outputs[].href changed to outputs[].destination.url
• outputs[].type changed to outputs[].mediaType
• outputs[].storage removed or changed to storageType (only for Azure/Dropbox)
• Media type is correct for output format
• Multiple outputs don't exceed limit (25)
• Embedded storage not used for images

Output configuration: JPEG specific

• Quality uses string enum not numeric (e.g., "maximum" not 7)
• Quality value mapped correctly: 7 → "maximum", 5-6 → "high", 3-4 → "medium", 1-2 → "low"
• Using quality parameter (not compression)

Output configuration: PNG specific

• Compression uses V2 enum not V1 values (e.g., "maximum" not "small")
• Compression value mapped: "small" → "maximum", "medium" → "medium", "large" → "low"
• Using compression parameter (not quality)

Output configuration: PSD/TIFF specific

• No quality or compression parameters included
• Correct mediaType: "image/vnd.adobe.photoshop" or "image/tiff"
• Only structural field changes applied

Document creation specific

• resolution is an object {"unit": "density_unit", "value": 72} (not an integer)
• depth is an integer (e.g., 8) not a string (e.g., "8")
• Color mode "grayscale" used (not "gray")
• fill: "backgroundColor" (V1 camelCase) → fill: "background_color" (V2 snake_case); camelCase is rejected in V2
• fill object form (V2): {"solidColor": {"red": N, "green": N, "blue": N}} for custom color
• depth value is mode-dependent: bitmap→1 only; grayscale/rgb/hsb→8,16,32; cmyk/lab/multichannel→8,16; indexed/duotone→8 only
• solid_color_layer fill uses fill.solidColor.{red,green,blue} (not fills[0].solidColor.rgb.*)
• fontColor.cmyk.yellowColor → fontColor.cmyk.yellow; fontColor.lab.luminance → fontColor.lab.l
• fontColor rgb/cmyk/gray/lab-l: V1 accepted 0–65535; V2 max is 32768 (use 32768 if V1 value exceeds it)
• fontColor lab a/b: V1 accepted 0–65535; V2 max is 16384 (use 16384 if V1 value exceeds it)
• apply.{from, to} is optional per characterStyles entry — omitting it applies the style to the full text; include it only when styling a specific character range
• Source/destination URLs are fully percent-encoded (no unencoded spaces or special chars)

Export layers specific

• cropMode layer_bounds only used for single-layer export; trim_to_transparency and document_bounds work for all export types
• Multi-layer export does not request PSD format (use JPEG, PNG, or TIFF)
• Default JPEG quality is photoshop_max if omitted; default PNG compression is default (level 6)

ICC profile specific

• iccProfile not used with PSDC outputs (remove or switch to another format)
• Standard profile names match exactly (including spaces and punctuation)
• CMYK output requires custom ICC profile (not standard)
• imageMode set correctly ("rgb", "grayscale", or "cmyk" for custom)

Status checking

• Status endpoint uses v2 path
• Handling all status values (pending, running, succeeded, failed)
• Error details handled as array
• Polling with appropriate interval (5 seconds recommended)
• Timeout handling implemented

Authentication

• Same OAuth token used (no change needed)
• Authorization header present
• x-api-key header present

Appendix: Common error codes

Quick command reference

Complete migration example

V1 (Multiple Calls):

# Call 1: Auto tone
curl -X POST https://image.adobe.io/lrService/autoTone \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -d '{"inputs": {"href": "<URL>"}, "outputs": [...]}'

# Call 2: Status check
curl -X GET https://image.adobe.io/lrService/status/{jobId1} \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey"

# Call 3: Apply edits
curl -X POST https://image.adobe.io/lrService/edit \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -d '{"inputs": {"href": "<URL>"}, "options": {...}, "outputs": [...]}'

# Call 4: Status check
curl -X GET https://image.adobe.io/lrService/status/{jobId2} \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey"

V2 (Single Call):

# Single combined request
curl -X POST https://photoshop-api.adobe.io/v2/edit \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {
    "source": {
      "url": "<INPUT_URL>"
    }
  },
  "edits": {
    "autoTone": true,
    "light": {
      "exposure": 1.2,
      "contrast": 10
    },
    "color": {
      "saturation": 15
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "<OUTPUT_URL>"
      },
      "mediaType": "image/jpeg",
      "quality": "high"
    }
  ]
}'

# Single status check
curl -X GET https://photoshop-api.adobe.io/v2/status/{jobId} \
  -H "Authorization: Bearer $token" \
  -H "x-api-key: $apiKey"

Document version

Version: 1.19 Created: October 29, 2025 Last Updated: May 6, 2026

Coverage:

• All migration guides consolidated
• Artboard migration: images/source structure, artboardSpacing, validation rules, common issues
• Execute-actions migration: ActionJSON stringification, additionalContents rename, resource limits
• Complete endpoint mappings (depth blur marked not yet supported)
• Storage options reference (with ACP clarification, no leading slash in CC paths)
• Common issues and solutions
• Code transformation examples
• Validation checklists
• LLM interaction patterns
• v2-whats-new.md: reorganized API-first — execute-actions (UXP script execution, UXP adhoc file output via scriptOutputPattern, published action files), generate-manifest (artboard type, smart object extraction, rich layer metadata), create-composite (smart object reworked API + SVG support, linked smart objects including resize, text rendering engine + new character styles, group layers, ICC profiles); architectural improvements (TODOs); storage options callout; dropped granular protection, multiple outputs, atomic multi-op sections
• v2-api-catalog.md: complete per-endpoint behavioral comparison with breaking changes checklist
• XMP with Masks migration patterns (V1 → V2)
• XMP with Orientation override (V2 new capability)
• Creative Cloud Storage (ACP) clarifications
• Layer processing order (V2 top-down, V1 bottom-up)
• additionalContents / __ADDITIONAL_CONTENT_0__ (replaces additionalImages)
• UXP object syntax and plugin-temp:/ output path
• scriptOutputPattern hosted destination ({"validityPeriod": 3600})
• resolution object format, integer depth, "grayscale" mode name
• protection array replaces locked/isLocked; group_layer type
• operation.type: "edit" required (not inferred)
• referenceLayer (not relativeTo) for relative placement
• Pixel mask: pixelMask, offset.horizontal/offset.vertical, userMask, isClipped, pixelMask.delete for removal (all edit layer types)
• Font color value ranges: rgb/cmyk/gray 0–32768, lab l 0–32768 / a,b -16384–16384
• Export layers: cropMode (all export types; layer_bounds single-layer only), PSD restriction, defaults
• ICC profile support: standard/custom profiles, CMYK via custom, PSDC restriction
• Color mode and bit depth validation tables by export path
• Cloud PSD mediaType document/vnd.adobe.cpsd+dcxucf
• Manifest response format changes: layer type renames (including background_layer, no typeAttributes on background entries), bounds format, thumbnail object, artboard layers[] key, document field renames
• Composite API V1→V2 complete field-level diff (all 4 V1 endpoints, all 7 layer types, output formats)
• Artboard API V1→V2 complete field-level diff (input restructure, storage mapping, quality/compression enums, crop mode, status response)
• Adjustment layer operations: adjustments.type discriminant required, type mapping table, exposureValue rename, hue/sat hueSaturationAdjustments[] restructure, localRange, parameter ranges, transformMode not applicable
• Text layer operations: character style range off-by-one (V1 to=length → V2 apply.to=inclusive end index), font.postScriptName, text.frame area/point types, bounds conversion, font options rename, textOrientation
• Smart object operations: smartObject.smartObjectFile.source.url path, isLinked, resize-with-linked-SO rasterization behavior, SVG support, supported source file types (PSD, JPEG, PNG, TIFF, SVG, AI, PDF); SVG and AI added in V2; AI files require Create PDF Compatible File option in Illustrator
• /pie/psdService/text migration: no declarative V2 equivalent; use execute-actions with ActionJSON (fixed edits) or UXP (conditional/iterative); decision table
• Blend mode location: top-level opacity/blendMode for most layers; blendOptions for smart_object_layer
• Layer transforms: V1 bounds → V2 transform {offset, dimension} with required transformMode: "custom"
• Alignment: V1 layer-level → V2 placement-level horizontalAlignment/verticalAlignment with placement.type: "custom"
• Document creation fill rename: "backgroundColor" → "background_color"; object form {solidColor:{...}}; depth-by-mode table

Composite API (/v2/create-composite) — key breaking changes reference

This section consolidates the highest-impact breaking changes across all four V1 composite-family endpoints (documentCreate, documentOperations, renditionCreate, smartObject).

For the complete authoritative field-level diff, see Create Composite V1 Reference.

V1 endpoint to V2 mapping

All four V1 endpoints map to POST /v2/create-composite.

Top-level request envelope

Layer processing order: V1 = bottom-up (last first); V2 = top-down (first first). Referenced layers must appear earlier in the array in V2.

Layer type renames

Common layer property changes

Text layer critical changes

Font color value ranges

V1 accepted 0–65535 for all fontColor components. V2 enforces lower maximums:

All components are required and default to 0 when omitted. Usage: fontColor.rgb, fontColor.cmyk, fontColor.lab, fontColor.gray.

V2 rejects requests where any component exceeds its maximum. Cap values before sending:

• rgb, cmyk, gray, lab.l: cap at 32768 — e.g. V1 red: 40000 → V2 red: 32768
• lab.a, lab.b: cap at 16384 — e.g. V1 a: 17000 → V2 a: 16384

Adjustment layer critical changes

Solid color layer critical changes

V1 used fills (plural array) with nested solidColor.rgb wrapper. V2 uses fill (singular object) with solidColor directly containing color components.

V1: {"fills": [{"solidColor": {"rgb": {"red": 255, "green": 0, "blue": 0}}}]}

V2: {"fill": {"solidColor": {"red": 255, "green": 0, "blue": 0}}}

Error when using V1 structure: "edits.layers[0].fill: fill is required when adding a solid color layer".

Output format changes

Features missing in V2

Artboard API (/v2/create-artboard) — key breaking changes reference

For the complete authoritative field-level diff, see Create Artboard V1 Reference.

Endpoint

Request envelope (breaking change)

data-variant=warning

data-slots=text

Input storage mapping

Output field changes

JPEG quality mapping

PNG compression mapping

New output formats in V2

document/vnd.adobe.cpsd+dcxucf (PSDC), application/json (JSON manifest) — not in V1.

Status response changes

Execute Actions API (/v2/execute-actions) — key breaking changes reference

For the complete authoritative field-level diff, see Execute Actions V1 Reference.

Endpoints covered

The only known API-visible gap is Neural Filters (Depth Blur), which are not yet available in V2.

Request envelope (breaking)

ActionJSON format (critical breaking change)

V1 options.actionJSON was an array of inline JSON objects. V2 requires ActionJSON as a stringified JSON string inside options.actions[].source.content with contentType: "application/json".

// V1
{"options": {"actionJSON": [{"_obj": "convertMode", "to": {"_enum": "colorSpaceMode", "_value": "grayscale"}}]}}

// V2
{"options": {"actions": [{"source": {"content": "[{\"_obj\":\"convertMode\",\"to\":{\"_enum\":\"colorSpaceMode\",\"_value\":\"grayscale\"}}]", "contentType": "application/json"}}]}}

Additional images/contents rename

Use __ADDITIONAL_CONTENT_N__ where N is the exact index from the original V1 placeholder — do NOT renumber. The old ACTION_JSON_OPTIONS_ADDITIONAL_IMAGES_N format is accepted by V2 for backward compatibility but __ADDITIONAL_CONTENT_N__ is the authoritative format per the V2 API schema.

.atn action source nesting

V1 supported a single action per request. V2 allows up to 10 actions executed in sequence (.atn files and inline ActionJSON can be mixed).

Font options rename

Stochastic filter validation caveats

Several Photoshop filter actions use an internal random seed that differs between V1 and V2 rendering engines. Pixel-diff comparison is not a valid acceptance test for payloads containing these filters — expect 50–80% pixel differences even when the ActionJSON is semantically identical and correctly migrated.

Known stochastic _obj values:

Recommended validation alternatives for stochastic filters:

• Histogram comparison (channel mean/stddev within acceptable delta)
• Structural Similarity Index (SSIM ≥ threshold)
• Mean-color comparison per region
• Skip pixel validation entirely and validate only the response status and output file existence

Removed V1 options

Output field renames

Resource limits

End of LLM Migration Reference Guide