API documentation

Conversion using the API is done in three steps:

1 Send your image
Call the /convert endpoint to submit your HDR image along with the specifications for the sizes and qualities you wish to obtain.
2 Check status
Use the /status endpoint to check the conversion's progress.
3 Download results
Once the conversion is complete, call the /download endpoint to retrieve a ZIP file containing all generated images.

To call the API, perform an HTTPS request to api.hdrjpg.com including your API key in a header called api-key.

Use a testing API key while working on your integration to avoid incurring any costs:

/convert POST /status GET /download GET /delete DELETE

Receives a HEIC (Apple), JPG (Android UltraHDR) or EXR HDR image file to be converted to the specified variants. Returns the complete specification of the conversion, which includes the unique conversion identifier in the form of an UUID.

curl -X POST https://api.hdrjpg.com/convert \
    -H 'api-key: {*JkDvPSycblQw8gGLTa6i3q04OSJrO0SglJZoqI8V*}' \
    -F 'sourceImage=@IMG_1122.HEIC' \
    -F 'variant=[{"width": 1200, "format": "jpeg-xt"}, {"width": 1200, "format": "jpeg-xl"}]'

Parameter name Description

sourceImage The source image in HEIC (Apple), JPG (Android UltraHDR) or EXR format.

Parameter name	Description
sourceImage	The source image in HEIC (Apple), JPG (Android UltraHDR) or EXR format.
variant	Specifies the conversion parameters for the desired output image. Pass variants as JSON: `{ "fileName": "image", "width": 1200, "height": 800, "format": "jpeg-xt", "baseQuality": 95, "gainmapQuality": 90 }` fileName Name of the resulting file (without extension). Use only characters a-z, 0-9, underscores, or hyphens. Automatically generated if omitted. width Resizes the image to fit within the specified width. height Resizes the image to fit within the specified height. If both width and height are provided, the image will be scaled proportionally to fit within both dimensions, preserving the aspect ratio, and ensuring neither width nor height is exceeded by the output size. The maximum output image size is 4000x4000 pixels. extrapolate Whether to extrapolate when resizing the image to the requested width or weight if it's larger than the source image. Defaults to false. format Specifies the desired output format, the following values are accepted: jpeg-xt The response will contain an HDR JPEG-XT file with the .jpg extension. This files can be used straightaway in HTML pages just like any other jpg file, they display in HDR on compatible devices and fallback to a standard dynamic range image on non-compatible devices. jpeg-xl The response will contain an HDR JPEG-XL file with the .jxl extension. avif The response will contain an HDR AVIF file with the .avif extension. There is a limit of 4 megapixels when outputting AVIF files. Final size will be downscaled to fit if the requested resolution exceeds the maximum megapixels supported for AVIF files. jpeg For convenience, you can also request a regular non-HDR JPEG file as part of your conversion. This files do not show in HDR, and appear in your conversion with the .sdr.jpg extension. baseQuality The quality of the image. Default quality is 95 gainmapQuality When specifying the jpeg-xt format, the quality of the gainmap can be optionally specified. If not specified, the same baseQuality will be used. Quality values are numbers from 0 to 100, where 0 is the lowest quality possible, and a 100 is the highest quality possible (not lossless). onSdr Specifies what to do if the source image is found to be a non-HDR image. The default action is fail. fail The conversion will be marked as failed, and no images will be generated, even if other variants could potentially produce one. The failed conversion will not count against your quota. skip This variant will be marked as skipped; images may still be generated if other variants allow for non-HDR conversions. If other files are produced, the conversion will still count towards your quota. continue The variant image will still be generated using the standard dynamic range source image, but it will not be in HDR. The conversion will still count towards your quota. expandToHdr The source's dynamic range will be expanded to HDR, making it look perceptually consistent with the original image but taking advantage of HDR's extended brightness capabilities. Some HEIC images may not be in HDR if they were taken with devices that do not support HDR, such as older generation iPads, iPhones, or Android phones. Specifying multiple variants You can obtain multiple image formats and size combinations in a single request by passing a JSON array of variants, like this: `[ { "width": 1200, "format": "jpeg-xt" }, { "width": 1200, "format": "jpeg-xl" }, { "width": 1200, "format": "avif" }, { "width": 600, "format": "jpeg-xt" }, { "width": 600, "format": "jpeg-xl" }, { "width": 600, "format": "avif" } ]` Requests with multiple variants count as one single conversion, meaning each conversion from one source image will still be charged (if applicable) as one even if it procudes multiple output files.

variant

Specifies the conversion parameters for the desired output image. Pass variants as JSON:

{
    "fileName": "image",
    "width": 1200,
    "height": 800,
    "format": "jpeg-xt",
    "baseQuality": 95,
    "gainmapQuality": 90
}

fileName

Name of the resulting file (without extension). Use only characters a-z, 0-9, underscores, or hyphens. Automatically generated if omitted.
width

Resizes the image to fit within the specified width.
height

Resizes the image to fit within the specified height.

extrapolate

Whether to extrapolate when resizing the image to the requested width or weight if it's larger than the source image. Defaults to false.
format

Specifies the desired output format, the following values are accepted:
- jpeg-xt
  
  The response will contain an HDR JPEG-XT file with the .jpg extension. This files can be used straightaway in HTML pages just like any other jpg file, they display in HDR on compatible devices and fallback to a standard dynamic range image on non-compatible devices.
- jpeg-xl
  
  The response will contain an HDR JPEG-XL file with the .jxl extension.
- avif
  
  The response will contain an HDR AVIF file with the .avif extension.
  
  There is a limit of 4 megapixels when outputting AVIF files. Final size will be downscaled to fit if the requested resolution exceeds the maximum megapixels supported for AVIF files.
- jpeg
  
  For convenience, you can also request a regular non-HDR JPEG file as part of your conversion. This files do not show in HDR, and appear in your conversion with the .sdr.jpg extension.
baseQuality

The quality of the image. Default quality is 95
gainmapQuality

When specifying the jpeg-xt format, the quality of the gainmap can be optionally specified. If not specified, the same baseQuality will be used.
Quality values are numbers from 0 to 100, where 0 is the lowest quality possible, and a 100 is the highest quality possible (not lossless).
onSdr

Specifies what to do if the source image is found to be a non-HDR image. The default action is fail.
- fail
  
  The conversion will be marked as failed, and no images will be generated, even if other variants could potentially produce one. The failed conversion will not count against your quota.
- skip
  
  This variant will be marked as skipped; images may still be generated if other variants allow for non-HDR conversions. If other files are produced, the conversion will still count towards your quota.
- continue
  
  The variant image will still be generated using the standard dynamic range source image, but it will not be in HDR. The conversion will still count towards your quota.
- expandToHdr
  
  The source's dynamic range will be expanded to HDR, making it look perceptually consistent with the original image but taking advantage of HDR's extended brightness capabilities.
Some HEIC images may not be in HDR if they were taken with devices that do not support HDR, such as older generation iPads, iPhones, or Android phones.

Specifying multiple variants

You can obtain multiple image formats and size combinations in a single request by passing a JSON array of variants, like this:

[
    {
        "width": 1200,
        "format": "jpeg-xt"
    },
    {
        "width": 1200,
        "format": "jpeg-xl"
    },
    {
        "width": 1200,
        "format": "avif"
    },
    {
        "width": 600,
        "format": "jpeg-xt"
    },
    {
        "width": 600,
        "format": "jpeg-xl"
    },
    {
        "width": 600,
        "format": "avif"
    }
]

Return

An HTTP 200 status code is returned if the conversion request is accepted. The complete details of the conversion entity are returned as a JSON object in the response body, which includes a unique UUID identifier that can be used to reference this conversion when calling other endpoints.

Returns information about the status of a conversion. Also includes information on the status of each individual variant being converted.

curl -G https://api.hdrjpg.com/status \
    -H 'api-key: {*JkDvPSycblQw8gGLTa6i3q04OSJrO0SglJZoqI8V*}' \
    -d "conversionUuid={*f253d8e7-8f6d-4351-8e77-a123f45474b9*}"

Parameter name	Description
conversionUuid	The UUID of the conversion, as obtained after calling the /convert endpoint.

Return

An HTTP 200 status code is returned if the conversion was found. The complete details of the conversion entity are returned as a JSON object in the response body.

Downloads a ZIP file that contains all the images files that resulted from a conversion.

curl -G https://api.hdrjpg.com/download \
    -H 'api-key: {*JkDvPSycblQw8gGLTa6i3q04OSJrO0SglJZoqI8V*}' \
    -d "conversionUuid={*f253d8e7-8f6d-4351-8e77-a123f45474b9*}" \
    --output result.zip

You should wait until the conversion status changes to Ready before being able to download the resulting ZIP file. Query the /status endpoint to obtain information about the status of a conversion.

Parameter name	Description
conversionUuid	The UUID of the conversion, as obtained after calling the /convert endpoint.

Deletes a conversion.

curl -X DELETE https://api.hdrjpg.com/delete \
    -H 'api-key: {*JkDvPSycblQw8gGLTa6i3q04OSJrO0SglJZoqI8V*}' \
    -d "conversionUuid={*f253d8e7-8f6d-4351-8e77-a123f45474b9*}"

If the conversion is in progress, it will be canceled. If all files have already been converted, it will still count towards your conversion quota. Once deleted, the resulting files from this conversion will no longer be available for download.

Parameter name	Description
conversionUuid	The UUID of the conversion, as obtained after calling the /convert endpoint.

Return

The complete details of the conversion entity are returned as a JSON object in the response body.