Skip to main content

Photo Formats

Endpoint Overview​

  • Endpoint Name: Photo Formats
  • Purpose: Retrieves the list of configured image formats.
  • Method: GET
  • URL: /{version}/photos/formats

Authentication​

  • Authentication Type: None

Request​

Headers​

Header NameRequiredDescription
acceptYesapplication/json

Path Parameters​

ParameterTypeDescription
versionstringThe version of the API to be used. Allowed values: v2.

Query Parameters​

None.

Response​

Response Codes​

HTTP Status CodeMeaning
200Successful request
404Not Found (resource does not exist)
500Internal Server Error

Response Body​

Data structure​

  • meta: Contains general information related to the request performed (Object)
    • apiVersion: The current version of the API endpoint that generated the response (String)
    • generatedAt: The UTC timestamp of the response (String)
  • items: An array of format objects (Array)
    • Name: The name of the format; formats starting with the _ character are system-reserved formats (String)
    • Instructions: Set of instructions that can be used to get the specified format from Cloudinary. This value should substitute the formatInstructions placeholder on the templateUrl properties of pictures (String)
    • AspectRatio: The aspect ratio of this format, if specified in the configuration (String)
    • Extension: The file extension to be added after templateUrl (if set) when Cloudinary is configured with the strict option. Use this if it is needed to specify the output format to be returned

Successful Response Example​

Request GET https://acme.org/v2/photos/formats

Response

▼ "root": {
▼ "meta": {
"apiVersion": "2.0"
"generatedAt": "2020-07-30T12:54:25.2644927Z"
}
▼ "items": [
▼ "0": {
"Name": "thumbnail"
"Instructions": "t_thumbnail"
"AspectRatio": "3:2"
"Extension": ".jpg"
}
▼ "1": {
"Name": "wide"
"Instructions": "t_wide"
"AspectRatio": "16:9"
"Extension": ""
}
▼ "2": {
"Name": "detail"
"Instructions": "t_detail"
"AspectRatio": "6:5"
"Extension": ".jpg"
}
▼ "3": {
"Name": "thumb-face"
"Instructions": "t_thumbface"
"Extension": ".jpg"
}
▼ "4": {
"Name": "thumb-face-preset"
"Instructions": "t_thumbfacepreset"
"Extension": ".jpg"
}
▼ "5": {
"Name": "sponsor-logo"
"Instructions": "t_sponsorlogo"
"AspectRatio": "2:1"
"Extension": ".jpg"
}
▼ "6": {
"Name": "story-header"
"Instructions": "t_storyheader"
"AspectRatio": "16:9"
"Extension": ".jpg"
}
▼ "7": {
"Name": "story-wide"
"Instructions": "t_storywide"
"AspectRatio": "16:9"
"Extension": ".jpg"
}
▼ "8": {
"Name": "list-card"
"Instructions": "t_listcard"
"AspectRatio": "16:9"
"Extension": ".jpg"
}
▼ "9": {
"Name": "featured-big"
"Instructions": "t_featuredbig"
"AspectRatio": "1270:846"
"Extension": ".jpg"
}
▼ "10": {
"Name": "featured-small"
"Instructions": "t_featuredsmall"
"AspectRatio": "979:652"
"Extension": ".jpg"
}
▼ "11": {
"Name": "Vertical banner"
"Instructions": "t_verticalbanner"
"AspectRatio": "1:2"
"Extension": ".jpg"
}
▼ "12": {
"Name": "_preview"
"Instructions": "w_400,h_225,c_fill,q_auto,g_auto,f_jpg"
}
▼ "13": {
"Name": "_thumb"
"Instructions": "w_250,h_250,c_thumb,g_auto,q_auto,f_jpg"
"AspectRatio": "1:1"
}
▼ "14": {
"Name": "_detail"
"Instructions": "w_700,h_700,c_fit,q_auto:low,f_jpg"
}
▼ "15": {
"Name": "_originalLowQuality"
"Instructions": "q_auto:low,f_jpg"
}
▼ "16": {
"Name": "_original"
}
]
}

Error Response Example​

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "traceId": "00-136f600b8c8d7ff6adc6c91ad120030a-40a7c87bf5ee8fdf-00"
}

Common Errors and Troubleshooting​

  • List common pitfalls and errors users may encounter
  • Provide clear guidance on how to resolve these issues
  • Provide links or references to related API endpoints for easy navigation