Output Types Migration Guide

Overview

Adobe Photoshop API v2 introduces significant changes to output format specifications. This guide covers the structural changes, field renaming, and quality/compression parameter transformations for all output types: JPEG, PNG, PSD, and TIFF.

Summary of changes

All output formats in v2 share common structural changes:

Structural changes (all output types)

Key structural changes:

1. Destination Object: URLs are now nested in a destination object.

2. Storage Type:

   • v1: storage field required for all outputs.
   • v2: storageType only needed for Azure Blob Storage and Dropbox.
   • AWS S3 presigned URLs don't require storageType.

3. Media Type: Renamed from type to mediaType for clarity.

V1 output structure

{
  "outputs": [
    {
      "href": "https://example.com/output.jpg",
      "storage": "external",
      "type": "image/jpeg",
      "width": 1920,
      "quality": 7
    }
  ]
}

V2 output structure

{
  "outputs": [
    {
      "destination": {
        "url": "https://example.com/output.jpg"
      },
      "mediaType": "image/jpeg",
      "width": 1920,
      "quality": "maximum"
    }
  ]
}

Common output fields

All output types support these common fields:

Format support: color mode and bit depth

When exporting to different formats, the API automatically converts source images when the color mode or bit depth is not supported by the target format. The following tables describe supported values and fallback behavior for each export path.

data-variant=info

data-slots=text

data-variant=info

data-slots=text

data-variant=info

data-slots=text

Bit depth validation

Color mode validation

JPEG output migration

Quality parameter changes

The most significant change for JPEG outputs is the quality parameter transformation from numeric to descriptive string values.

V1 JPEG quality (numeric)

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

In the v1 API, you can use numeric values:

• Range: 1-7 (some versions supported 1-12)
• Higher number = better quality
• Default: 7 (maximum quality)

V2 JPEG quality (string enum)

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

In the v2 API, you use descriptive string values:

• "very_poor" - Lowest quality, smallest file size
• "poor" - Poor quality
• "low" - Low quality
• "medium" - Balanced quality and file size
• "high" - High quality
• "maximum" - Maximum quality
• "photoshop_max" - Photoshop maximum quality (recommended default)

JPEG quality mapping table

The quality parameter is optional. If not specified, the API uses different defaults based on the operation type:

• Create Composite (/v2/create-composite): Default quality is photoshop_max
• Generate Manifest (/v2/generate-manifest): Default quality for layer thumbnails is medium

Complete JPEG migration example

Key Transformations:

1. inputs[].href → image.source.url
2. outputs[].href → outputs[].destination.url
3. outputs[].type → outputs[].mediaType
4. quality: 7 → quality: "maximum"
5. storage: "external" removed (implicit for S3 URLs)

V1 Request:

{
  "inputs": [
    {
      "href": "https://my-bucket.s3.amazonaws.com/input.psd",
      "storage": "external"
    }
  ],
  "outputs": [
    {
      "href": "https://my-bucket.s3.amazonaws.com/output.jpg",
      "storage": "external",
      "type": "image/jpeg",
      "quality": 7,
      "width": 2000
    }
  ]
}

V2 Request:

{
  "image": {
    "source": {
      "url": "https://my-bucket.s3.amazonaws.com/input.psd"
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "https://my-bucket.s3.amazonaws.com/output.jpg"
      },
      "mediaType": "image/jpeg",
      "quality": "maximum",
      "width": 2000
    }
  ]
}

PNG output migration

Compression parameter changes

PNG outputs have expanded compression options in V2, offering more granular control over file size and compression speed.

V1 PNG compression

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

In the v1 API, you can use three compression levels:

• "small" - High compression (smaller files)
• "medium" - Balanced compression
• "large" - Low compression (larger files)

V2 PNG compression

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

In the v2 API, you can use ten compression levels (following zlib/libpng standards):

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

PNG compression mapping table

The compression parameter is optional. If not specified, the API uses default (level 6) for both Create Composite and Generate Manifest operations, which provides a good balance between file size and processing speed.

Complete PNG migration example

Key Transformations:

1. inputs[].href → image.source.url
2. outputs[].href → outputs[].destination.url
3. outputs[].type → outputs[].mediaType
4. compression: "medium" stays the same (but more options available)
5. storage field removed

V1 Request:

{
  "inputs": [
    {
      "href": "https://my-storage.com/input.psd",
      "storage": "external"
    }
  ],
  "outputs": [
    {
      "href": "https://my-storage.com/output.png",
      "storage": "external",
      "type": "image/png",
      "compression": "medium",
      "width": 1920
    }
  ]
}

V2 Request:

{
  "image": {
    "source": {
      "url": "https://my-storage.com/input.psd"
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "https://my-storage.com/output.png"
      },
      "mediaType": "image/png",
      "compression": "medium",
      "width": 1920
    }
  ]
}

PSD output migration

PSD format changes

Photoshop document (PSD) outputs have no format-specific parameters, like quality or compression. The only changes are the structural field renaming.

V1 PSD output

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

V2 PSD output

{
  "mediaType": "image/vnd.adobe.photoshop",
  "destination": {
    "url": "https://example.com/output.psd"
  }
}

Supported media types for PSD

V2 accepts both media type formats:

• "image/vnd.adobe.photoshop" (recommended)
• "vnd.adobe.photoshop" (legacy support)

Complete PSD migration example

Key Transformations:

1. Field renaming (same as other formats)
2. options → edits
3. No quality or compression parameters needed

V1 Request:

{
  "inputs": [
    {
      "href": "https://storage.example.com/document.psd",
      "storage": "external"
    }
  ],
  "options": {
    "layers": [
      {
        "name": "Background",
        "locked": false
      }
    ]
  },
  "outputs": [
    {
      "href": "https://storage.example.com/modified.psd",
      "storage": "external",
      "type": "image/vnd.adobe.photoshop"
    }
  ]
}

V2 Request:

{
  "image": {
    "source": {
      "url": "https://storage.example.com/document.psd"
    }
  },
  "edits": {
    "layers": [
      {
        "name": "Background",
        "protection": ["none"]
      }
    ]
  },
  "outputs": [
    {
      "destination": {
        "url": "https://storage.example.com/modified.psd"
      },
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}

TIFF output migration

TIFF format changes

TIFF outputs in the v2 API do not have compression options. Like PSD, the changes are purely structural.

V1 TIFF output

{
  "type": "image/tiff",
  "href": "https://example.com/output.tiff",
  "storage": "external"
}

V2 TIFF output

{
  "mediaType": "image/tiff",
  "destination": {
    "url": "https://example.com/output.tiff"
  }
}

Complete TIFF migration example

Key Transformations:

1. Standard field renaming
2. No compression parameters in v2
3. Common output fields still supported (width, height, etc.)

V1 Request:

{
  "inputs": [
    {
      "href": "https://storage.example.com/input.psd",
      "storage": "external"
    }
  ],
  "outputs": [
    {
      "href": "https://storage.example.com/output.tiff",
      "storage": "external",
      "type": "image/tiff",
      "width": 3000
    }
  ]
}

V2 Request:

{
  "image": {
    "source": {
      "url": "https://storage.example.com/input.psd"
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "https://storage.example.com/output.tiff"
      },
      "mediaType": "image/tiff",
      "width": 3000
    }
  ]
}

Multiple outputs

V2 supports generating multiple outputs in different formats from a single request (up to 25 outputs).

Multiple output example

V2 Request:

{
  "image": {
    "source": {
      "url": "https://storage.example.com/input.psd"
    }
  },
  "outputs": [
    {
      "destination": {
        "url": "https://storage.example.com/output-hq.jpg"
      },
      "mediaType": "image/jpeg",
      "quality": "maximum",
      "width": 2400
    },
    {
      "destination": {
        "url": "https://storage.example.com/output-preview.jpg"
      },
      "mediaType": "image/jpeg",
      "quality": "medium",
      "width": 800
    },
    {
      "destination": {
        "url": "https://storage.example.com/output.png"
      },
      "mediaType": "image/png",
      "compression": "maximum",
      "width": 1920
    },
    {
      "destination": {
        "url": "https://storage.example.com/output.psd"
      },
      "mediaType": "image/vnd.adobe.photoshop"
    }
  ]
}

This generates four outputs in a single API call:

1. High-quality JPEG at 2400px width
2. Medium-quality preview JPEG at 800px width
3. PNG with maximum compression at 1920px width
4. Original PSD with any edits applied

Storage type considerations

When to use storageType

In v2, the storageType field is optional and only required for specific storage providers:

Azure Blob Storage example

{
  "destination": {
    "url": "https://myaccount.blob.core.windows.net/container/output.jpg",
    "storageType": "azure"
  },
  "mediaType": "image/jpeg",
  "quality": "high"
}

Dropbox example

{
  "destination": {
    "url": "https://dropbox.com/path/to/output.jpg",
    "storageType": "dropbox"
  },
  "mediaType": "image/jpeg",
  "quality": "high"
}

Common migration errors

Using V1 field names

❌ Problem:

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

❌ Error:

Required field 'destination' is missing
Required field 'mediaType' is missing

✅ Solution:

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

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"
}

Invalid PNG compression

❌ Problem:

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

❌ Error:

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

✅ Solution:

Use V2 compression values:

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

Using JPEG quality for PNG

❌ Problem:

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

❌ Error:

'quality' parameter is not supported for PNG format

✅ Solution:

Use compression for PNG:

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

Missing storage type for Azure

❌ Problem:

{
  "destination": {
    "url": "https://myaccount.blob.core.windows.net/..."
  }
}

❌ Error:

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

✅ Solution:

{
  "destination": {
    "url": "https://myaccount.blob.core.windows.net/...",
    "storageType": "azure"
  }
}

Migration checklist

Use this checklist when migrating output configurations:

All Output Types

• Replace outputs[].href with outputs[].destination.url
• Replace outputs[].type with outputs[].mediaType
• Remove storage: "external" for AWS S3 presigned URLs
• Add storageType for Azure Blob Storage or Dropbox if applicable
• Verify common fields (width, height, maxWidth) if used
• Optionally add resample to control interpolation when width/maxWidth is set (JPEG, PNG, TIFF; defaults to bicubic)

JPEG specific

• Convert numeric quality values to string enums
• Map V1 quality values using the mapping table
• Quality is optional; defaults to photoshop_max for create-composite, medium for manifest thumbnails

PNG specific

• Update compression values to V2 enum
• Map V1 compression values using the mapping table
• Compression is optional; defaults to default (level 6)
• Ensure using compression not quality

PSD specific

• Use "image/vnd.adobe.photoshop" for mediaType
• No quality or compression parameters needed

TIFF specific

• Use "image/tiff" for mediaType
• No compression parameters in V2

Quick reference

Field name changes (all formats)

JPEG quality quick reference

PNG compression quick reference

Additional resources

• Execute Actions Endpoint
• Status Endpoint

Related migration guides:

• Migration Overview - Complete V1 to V2 migration overview
• Format Conversion Migration - Converting between formats
• ICC Profile Migration - Color management for output exports
• Actions Migration - Executing Photoshop actions
• Storage Solutions - Detailed storage configuration