Export Layers Migration Guide

Overview

This guide describes how to migrate exporting one or more layers from a document to the V2 /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)

Enum support (V2)

Crop mode (cropMode)

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
No
No
trim_to_transparency
Crop to tight bounds of non-transparent pixels.
Yes
Yes
Yes
document_bounds
Use full document (or artboard) bounds (default for document/multi-layer export).
Yes
Yes
Yes
data-variant=info

data-slots=text
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

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.

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

V1 (example)

curl -X POST "https://image.adobe.io/pie/psdService/renditionCreate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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 "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"
    }]
  }'

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

Sample: multi-layer export

V1 (example)

curl -X POST "https://image.adobe.io/pie/psdService/renditionCreate" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -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 "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"
    }]
  }'

Schema changes (multi-layer): Same as above. Note: 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.

Migration checklist for export layers

Last Updated: March 2026