Export layers migration guide

This guide describes how to migrate exporting one or more layers from a document to the /v2/create-composite endpoint: schema changes, enum support for single-layer export, PSD support (single-layer only; multi-layer does not support PSD as of now), default quality and compression, and sample v1/v2 requests.

Key differences (single-layer vs multi-layer export)

Single-layer export – One layer in output.layers; export that layer's pixels. Supports JPEG, PNG, TIFF, and PSD.
Multi-layer export – Two or more layers in output.layers; composite those layers to one raster file. Supports JPEG, PNG, and TIFF only. PSD is not supported for multi-layer export as of now.

Enum support (v2)

Crop mode (`cropMode`)

data-variant=info

data-slots=header,text

V1 migration note — single-layer output dimensions

V1 always exported single layers at document/canvas dimensions regardless of layer position or size. V2 defaults to layer_bounds, so the output is sized to the layer itself rather than the canvas. If your V1 workflow relied on canvas-sized output, set cropMode: "document_bounds" explicitly to preserve that behavior.

Controls the output bounding box for exported content. Supported for single-layer, multi-layer, and document export, with one restriction: layer_bounds is only valid for single-layer export.

Value

Description

Single-layer

Multi-layer

Document export

layer_bounds

Use the layer's own bounds (default for single-layer export).

Yes

trim_to_transparency

Crop to tight bounds of non-transparent pixels.

Yes

document_bounds

Use full document (or artboard) bounds (default for document/multi-layer export).

Yes

data-variant=warning

data-slots=header,text

INFO

Using layer_bounds with multi-layer or document export returns a validation error. Use trim_to_transparency or document_bounds instead.

Media type (`mediaType`)

For single-layer export, v2 supports: image/jpeg, image/png, image/tiff, image/vnd.adobe.photoshop (PSD). See Output Types Migration for full enum details.

Defaults when exporting layers

JPEG quality (when omitted): photoshop_max. Allowed values: very_poor, poor, low, medium, high, maximum, photoshop_max.
PNG compression (when omitted): default (level 6); you can also set medium, maximum, etc. See Output Types Migration – PNG.

ICC profile support for layer export

Both single-layer and multi-layer exports support the optional iccProfile field on the output. This enables ICC color space conversion (e.g., sRGB, Adobe RGB, grayscale, or custom profiles) when exporting specific layers.

Works with supported layer export formats that support ICC: JPEG, TIFF, PSD for single-layer; JPEG, TIFF for multi-layer (PNG does not support ICC profiles)
Each output in a request can have its own independent iccProfile
Mixed outputs are supported: some with iccProfile, some without, in the same request
Supports both standard and custom ICC profiles (see ICC Profile Migration for full schema details)

Example: single-layer export with ICC profile

{
  "outputs": [{
    "destination": {"url": "https://example.com/out.tif"},
    "mediaType": "image/tiff",
    "layers": [{"id": 1096}],
    "iccProfile": {
      "type": "standard",
      "name": "sRGB IEC61966-2.1"
    }
  }]
}

Example: multi-layer export with ICC profile

{
  "outputs": [{
    "destination": {"url": "https://example.com/out.jpg"},
    "mediaType": "image/jpeg",
    "layers": [{"id": 1096}, {"id": 996}],
    "quality": "high",
    "iccProfile": {
      "type": "standard",
      "name": "Adobe RGB (1998)"
    }
  }]
}

Sample: single-layer export

Schema changes (single-layer): inputs[].href → image.source.url; outputs[].href → outputs[].destination.url; outputs[].type → outputs[].mediaType; outputs[].layers remains per output. Optional in V2: cropMode, quality / compression as string enums.

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

V1 example

curl -X POST "https://image.adobe.io/pie/psdService/renditionCreate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"href": "https://my-bucket.s3.amazonaws.com/input.psd", "storage": "external"}],
    "outputs": [{
      "href": "https://my-bucket.s3.amazonaws.com/out.png",
      "storage": "external",
      "type": "image/png",
      "layers": [{"id": 1096}],
      "compression": "medium"
    }]
  }'

V2 example

curl -X POST "https://photoshop-api.adobe.io/v2/create-composite" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {"source": {"url": "https://my-bucket.s3.amazonaws.com/input.psd"}},
    "outputs": [{
      "destination": {"url": "https://my-bucket.s3.amazonaws.com/out.png"},
      "mediaType": "image/png",
      "layers": [{"id": 1096}],
      "cropMode": "trim_to_transparency",
      "compression": "medium"
    }]
  }'

Group and Artboard Layer PSD Export

When the single layer in outputs[].layers[] is a group layer or artboard layer and mediaType is image/vnd.adobe.photoshop, the exported PSD is editable — the layer hierarchy inside the group or artboard is preserved in the output file.

Example: Export Group Layer as Editable PSD

{
  "image": {"source": {"url": "https://example.com/input.psd"}},
  "outputs": [{
    "destination": {"url": "https://example.com/group-export.psd"},
    "mediaType": "image/vnd.adobe.photoshop",
    "layers": [{"id": 1076}]
  }]
}

Example: Export Artboard Layer as Editable PSD

{
  "image": {"source": {"url": "https://example.com/input.psd"}},
  "outputs": [{
    "destination": {"url": "https://example.com/artboard-export.psd"},
    "mediaType": "image/vnd.adobe.photoshop",
    "layers": [{"id": 18}]
  }]
}

Crop Mode for Group/Artboard PSD Export

cropMode

Behavior

layer_bounds (default)

Canvas sized to the bounds of the group or artboard layer.

document_bounds

Canvas sized to the full source document dimensions. Group/artboard layers are placed at their absolute position within the document canvas.

trim_to_transparency

Behaves the same as layer_bounds for group and artboard PSD export. Unlike raster exports where this crops to the tightest non-transparent bounding box, the PSD export uses the full group or artboard rect as the canvas. This is because the output is an editable layer tree, not a flat composite, so pixel-level trimming cannot be applied without rasterizing.

Linked Smart Objects Inside Groups and Artboards

data-variant=warning

data-slots=text

If the group or artboard layer contains a linked smart object, the export job will fail. The Photoshop API does not have access to the linked file at processing time, so the layer tree cannot be written to the output PSD. Ensure any linked smart objects inside the group or artboard are converted to embedded smart objects before exporting.

Sample: multi-layer export

Schema changes (multi-layer): Multi-layer export does not support PSD as of now; use mediaType: image/jpeg, image/png, or image/tiff only. cropMode supports trim_to_transparency and document_bounds (not layer_bounds). Use string enums for quality (e.g., maximum, photoshop_max) and compression for PNG.

V1 example

curl -X POST "https://image.adobe.io/pie/psdService/renditionCreate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [{"href": "https://my-bucket.s3.amazonaws.com/input.psd", "storage": "external"}],
    "outputs": [{
      "href": "https://my-bucket.s3.amazonaws.com/out.jpg",
      "storage": "external",
      "type": "image/jpeg",
      "layers": [{"id": 1096}, {"id": 996}],
      "quality": 7
    }]
  }'

V2 example

curl -X POST "https://photoshop-api.adobe.io/v2/create-composite" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $apiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "image": {"source": {"url": "https://my-bucket.s3.amazonaws.com/input.psd"}},
    "outputs": [{
      "destination": {"url": "https://my-bucket.s3.amazonaws.com/out.jpg"},
      "mediaType": "image/jpeg",
      "layers": [{"id": 1096}, {"id": 996}],
      "quality": "maximum",
      "cropMode": "trim_to_transparency"
    }]
  }'

Migration checklist for export layers

Use outputs[].destination.url, outputs[].mediaType, and outputs[].layers (V2 shape).
For multi-layer export, do not request PSD; use JPEG, PNG, or TIFF.
cropMode trim_to_transparency and document_bounds work for all export types; layer_bounds is single-layer only.
Use string enums for quality (JPEG) and compression (PNG); omit for defaults (photoshop_max / default).
iccProfile is optional on layer exports — add if you need color space conversion (see ICC Profile Migration).

Output Types Migration – JPEG quality and PNG compression enums, media types, and structural changes for all outputs
ICC Profile Migration – ICC profile schema, standard/custom profiles, and format support
Layer Operations Overview – Introduction to layer operations in V2
Composite Migration – Create-composite endpoint and layer operations
Migration Overview – Full V1 to V2 migration overview

Last Updated: March 2026

Export layers migration guide

Key differences (single-layer vs multi-layer export)

Enum support (v2)

Crop mode (cropMode)

Media type (mediaType)

Defaults when exporting layers

ICC profile support for layer export

Example: single-layer export with ICC profile

Example: multi-layer export with ICC profile

Sample: single-layer export

V1 example

V2 example

Group and Artboard Layer PSD Export

Example: Export Group Layer as Editable PSD

Example: Export Artboard Layer as Editable PSD

Crop Mode for Group/Artboard PSD Export

Linked Smart Objects Inside Groups and Artboards

Sample: multi-layer export

V1 example

V2 example

Migration checklist for export layers

Related guides

Crop mode (`cropMode`)

Media type (`mediaType`)