imgix APIs
Management API
Assets

Assets

Note: Some Asset Manager features (and therefore some Asset Manager API Operations) are Premium-only and may not be enabled for all accounts. Contact Support (opens in a new tab) or your Account Manager to find out more.

Asset Manager Asset operations are usually tied to a specific Source, specified by source_id.

Asset Operations

Open in Postman (opens in a new tab)

GET Asset operations require the Asset Manager Browse permission. All other Asset operations require the Asset Manager Edit permission.

EndpointMethodDescription
sources/:source_id/assetsGETRetrieve a list of assets from the Source.
sources/:source_id/assets/:origin_pathGETRetrieve details for a single asset in a Source source_id by asset_id.
sources/:source_id/assets/:origin_pathPATCHUpdate a single asset.
sources/:source_id/upload/:origin_pathPOSTUpload a single asset to the source_id Source at origin_path. See Uploading for more details.
sources/:source_id/assets/add/:origin_pathPOSTAdds a single asset to the Asset Manager from the origin. Adding an Asset for more details.
sources/:source_id/assets/refresh/:origin_pathPOSTRefresh, reprocess, and purge a single asset. See Refreshing an Asset for more details.

Asset Filters

FilterTypeNotes
categoriesString
colorsStringHex code (minus the #, e.g. 8ca091.
custom:<key>StringIf no value is passed for this filter it will return results that have the custom key set to any value. If a value is passed, it will return results that have the custom key set to that specific value.
face_countIntegerA single integer will return results with exactly that many faces. To filter on a range, use a : (e.g. 1:3 would return results with 1, 2, or 3 faces, 1: would return results with 1 or more faces and :2 would return results with 2 or fewer faces.
has_framesBoolean
keywordStringSearches across multiple pre-determined fields, such as origin_path, name, description, etc. Exact behavior is subject to change.
media_kindStringType of asset. Possible values: IMAGE, ANIMATION, DOCUMENT, VECTOR.
origin_pathString
tagsString
warning_adultIntegerAccepted values are 1 through 5 where 1 is least likely and 5 is most likely. To filter on a range, use a : (e.g. 1:3 would return results with values 1, 2, or 3, 3: would return results with values 3 or higher and :2 would return results with values 2 or lower.
warning_medicalIntegerBehavior is the same as for warning_adult above.
warning_racyIntegerBehavior is the same as for warning_adult above.
warning_spoofIntegerBehavior is the same as for warning_adult above.
warning_violenceIntegerBehavior is the same as for warning_adult above.

Asset Sorts

  • date_created
  • date_modified
  • file_size

Asset Attributes

FieldTypeUpdatable?Description
analyzed_content_warningsBooleanNoWhether asset has been analyzed for content warnings.
analyzed_facesBooleanNoWhether asset has been analyzed for the presence of faces.
analyzed_tagsBooleanNoWhether asset has been analyzed in order to generate tags.
categoriesListYesList of user-added categories to describe or organize the asset (e.g. “Editorial Images” or “Summer Campaign” or “Profile Pictures”.
color_modelStringNoDetected color model (e.g. “RGB” or “CMYK”).
color_profileStringNoDetected color profile (e.g. “Apple Wide Color Sharing Profile”).
colorsObjectNoDetected dominant colors. Keys are hex codes and values are floating point numbers representing the fraction of the image with that color. The percentage values will not necessarily add up to 1 because not every single color in the image will be returned.
content_typeStringNoDetected content type of the asset (e.g. image/jpeg, image/gif). Unsupported or unknown content types may have value application/octet-stream.
custom_fieldsObjectYesUser-added custom fields and values (e.g. { SKU: 1234 })
date_createdIntegerNoUnix timestamp of the first time this asset was added to the Asset Manager (note that this is often different from the first time an image has been processed by the imgix rendering service).
date_modifiedIntegerNoUnix timestamp of the last time this asset was modified, whether by an end-user or by an automated update.
descriptionStringYesUser-provided description of asset.
dpi_heightIntegerNoDPI of an image’s height.
dpi_widthIntegerNoDPI of an image’s width.
face_countIntegerNoNumber of faces detected in an image. Only relevant if analyzed_faces is true.
file_sizeIntegerNoAsset size in bytes.
has_framesBooleanNotrue if the asset is an animation (video or gif), false otherwise.
media_heightIntegerNoPixel height of asset.
media_kindStringNoType of asset. Possible values: IMAGE, ANIMATION, DOCUMENT, VECTOR.
media_widthIntegerNoPixel width of asset.
nameStringYesUser-provided name of asset. Will not change the origin-path.
origin_pathStringNoPath to the asset relative to the Source’s prefix.
source_idStringNoID of the Source this asset is associated with.
tagsObjectYesMachine-learning generated tags describing the image. Keys are tag text (e.g. “Dog”) and values are floating point numbers representing confidence level, with 0 being not confident and 1 being 100% confident.
uploaded_byStringNoID of the user who uploaded this asset via the Asset Manager UI, if it was uploaded.
uploaded_by_apiBooleanNotrue if the asset was uploaded via an API request, false otherwise.
video_aspect_ratioStringNoAspect ratio of a video.
video_audio_channel_layoutStringNoAudio channel layout of a video.
video_durationIntegerNoVideo duration expressed in seconds.
video_error_messageStringNoError message when unable to process video. null otherwise.
video_has_audioBooleanNotrue if a video has audio, false otherwise.
video_imgix_statusStringNoProcessing status of a video. Possible values:
TRANSCODE_STARTED: The video file is processing
VIDEO_READY: The video is processed and ready for playback
ERRORED: There was an issue with processing the video
video_max_stored_frame_rateFloatNoMax stored frame rate of a video
video_max_stored_resolutionStringNoMax stored resolution of a video
video_max_stored_resolution_xIntegerNoMax stored width of a video
video_max_stored_resolution_yIntegerNoMax stored height of a video
video_playback_urlStringNoVideo playback URL
warning_adultIntegerNoNumber from 0 to 5 describing the content warning level. Only relevant if analyzed_content_warnings is true. 0 means unknown and 1 is low likelihood while 5 is high likelihood.
warning_medicalIntegerNoBehavior is the same as for warning_adult above.
warning_racyIntegerNoBehavior is the same as for warning_adult above.
warning_spoofIntegerNoBehavior is the same as for warning_adult above.
warning_violenceIntegerNoBehavior is the same as for warning_adult above.

Paginating through Asset Lists

Responses containing lists of assets will also include a cursor that looks like this:

"cursor": {
  "current": "20",
  "hasMore": true,
  "next": "22",
  "totalRecords": "68",
}

current corresponds to the the current page, and next is the cursor value you should pass in to retrieve the next page of results, provided that hasMore is true. totalRecords provides a count of the total records found by the search query; however, it returns a maximum count of 1,001 regardless of how many records actually match the query.

Uploading Assets to a Source

The imgix Management API allows you to upload directly to your cloud-storage-backed Source (Azure, GCS, or S3). The API will upload to the same bucket your Source is configured to read from. Uploading to Web Folder or Web Proxy Sources is not supported.

In order to enable uploading for a Source, you need to provide credentials that enable imgix access to upload to your cloud storage. We will refer to these as your Source’s upload_credentials . The credentials you provided when you first set up your Source and that the imgix rendering service uses to fetch assets from your origin are stored separately, and we will refer to these as your deployment_credentials.

The rendering service does not need write permissions to fetch assets, so we highly recommend that you do not use the same credentials for your upload_credentials and your deployment_credentials.

Note you can only upload assets to a path that does not already exist at your Origin. If an asset already exists at that path, our API will return a 409 Conflict error to indicate an already existing asset at the origin.

Upload Credentials Attributes

FieldRequired?Description
typeYesAccepted values are azure, gcs, and s3.
azure_sas_stringYesRequired for azure-type Sources only. Read more on how to create Azure credentials.
gcs_access_keyYesRequired for gcs-type Sources only.
gcs_secret_keyYesRequired for gcs-type Sources only. Will not be returned once it is provided. Read more on how to create GCS credentials.
s3_access_keyYesRequired for s3-type Sources only.
s3_secret_keyYesRequired for s3-type Sources only. Will not be returned once it is provided. Read more on how to create S3 credentials.

To provide upload_credentials, make a PATCH request to your Source with the new credentials and Source type inside of an upload_credentials object. The type of the upload_credentials must match the Source type and the provided credentials must be valid and supply write permissions to the Source cloud storage bucket.

Here’s an example request to update an S3 Source with upload credentials:

PATCH /api/v1/sources/5ae507164b595f0001e048bc
 
{
  "data": {
    "attributes": {
      "upload_credentials": {
        "s3_access_key": "<s3-access-key>",
        "s3_secret_key": "<s3-secret-key>",
        "type": "s3"
      }
    },
  "id": "5ae507164b595f0001e048bc",
  "type": "sources"
  }
}

Once your Source has appropriate upload_credentials, you can upload an asset by making a POST request to api/v1/sources/:source_id/upload/:origin_path with the body being the raw asset data. The response will be the same as a GET request to api/v1/assets/:source_id/:origin_path.

Adding an Asset

The add endpoint queues a path from your origin to be added to the Asset Manager. For an asset to be added successfully:

  • The asset path must exist
  • The asset path must return a 200 response from the origin
  • Your Source must have sufficient read permissions

The add endpoint is useful if you are not using the upload endpoint or the Asset Manager UI (opens in a new tab) to upload an asset, and if you are relying on imgix to regularly crawl your origin for new assets.

To add an asset, issue a POST request to sources/:source_id/assets/add/:origin-path with an empty POST body.

Here’s an example:

POST api/v1/sources/5ae507164b595f0001e048bc/assets/add/marketing/logo.png
{}

This returns a 202 empty response from our server. Note the add endpoint only queues an asset for processing. After you've queued an asset, you can poll the get asset endpoint to get the status of the asset after it has been queued.

Refreshing an Asset

Refreshing an asset is useful when an asset has been updated at origin but the automated refresh process imgix uses (which can take 24-48 hours) has not picked up the change yet. In these cases, making a request to refresh the asset will:

  1. Refetch the asset from the origin.
  2. Reprocess the asset if the ETag (opens in a new tab) has changed since the last time the asset was processed.
    • If the asset has never been pulled into the Asset Manager before, the refresh endpoint will pull the asset into the Asset Manager.
  3. Purge the asset from all imgix caches. Note that you may still have to hard refresh your browser to see any updated assets.

To refresh an asset, issue a POST request to sources/:source_id/assets/refresh/:origin-path with an empty POST body.

Here’s an example:

POST api/v1/sources/5ae507164b595f0001e048bc/assets/refresh/marketing/logo.png
{}

If the ETag of the asset differs from the last time the asset was processed the asset will be reprocessed. The asset will then be purged and the response will be similar to the one returned when issuing a GET request to sources/:source_id/assets/:origin_path.

Using Upload Sessions

We recommend using the upload session flow for uploading assets larger than 50MB, such as videos. This is a multi-part, sequential flow that involves creating a session, uploading a file for that session, and finally closing the session. Note: This is currently supported only for Amazon S3 and Google Cloud Storage sources, and supports file sizes up to 5GB.

Upload Session Flow:

  1. Create an upload session. One session should be created per uploaded file. The session and presigned URL will stay open for 8 hours.
  2. Use the session's presigned URL to perform an HTTP PUT to upload the file
  3. Close the session when the upload is complete. Closing the session is not required, but it will expedite asset processing and is strongly recommended. Unclosed sessions will close after 8 hours.
  4. Check upload status to follow processing states. See below for valid upload session states.

Sessions have the following states to track your asset's upload status:

  • PENDING: The session is open.
  • CLOSED: The uploaded asset is being processed by our system.
  • COMPLETE: Processing has been completed. Note that video assets will require additional time to complete the transcoding process.
  • CANCELED: The session has been canceled.

Python Example of Full Upload Session Flow

import os
import requests
 
 
API_KEY = ""
BASE_URL = "https://api.imgix.com/api/v1/"
SOURCE_ID = ""
ORIGIN_PATH = ""
LOCAL_FILE = "/path/to/file"
 
 
session = requests.post(
    f"{BASE_URL}sources/{SOURCE_ID}/upload-sessions/{ORIGIN_PATH}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()
 
with open(LOCAL_FILE, "rb") as f:
    requests.put(
        session["data"]["attributes"]["url"],
        f.read(),
        headers={"Content-Type": "image/jpeg"},
    )
 
session_id = session["data"]["id"]
closed_session = requests.post(
    f"{BASE_URL}sources/{SOURCE_ID}/upload-sessions/{session_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

Asset Examples

Retrieving details for a single asset

GET /api/v1/assets/5b81e81539ddc50001a5d955/luke.jpg
{
  "data": {
    "attributes": {
      "analyzed_content_warnings": true,
      "analyzed_faces": false,
      "analyzed_tags": true,
      "categories": [
        "Summer Photos"
      ],
      "color_model": "RGB",
      "color_profile": null,
      "colors": {
        "dominant_colors": {
          "#353237": 0.11076190322637558,
          "#545355": 0.07571428269147873,
          "#65a6fa": 0.08052381128072739,
          "#90c4f8": 0.06638095527887344,
          "#927942": 0.002190476283431053,
          "#a39173": 0.0018095237901434302,
          "#b1e7fe": 0.09242857247591019,
          "#e77abc": 0.005857143085449934,
          "#eebbc0": 0.0033333334140479565,
          "#f8f78e": 0.011857142671942711
        }
      },
      "content_type": "image/jpeg",
      "custom_fields": {
        "Dog name": "Luke"
      },
      "date_created": 1569633867,
      "date_modified": 1596825719,
      "description": null,
      "dpi_height": 300,
      "dpi_width": 300,
      "face_count": 0,
      "file_size": 357679,
      "has_frames": false,
      "media_height": 1825,
      "media_kind": "IMAGE",
      "media_width": 1704,
      "name": null,
      "origin_path": "/luke.jpg",
      "source_id": "5b81e81539ddc50001a5d955",
      "tags": {
        "Canidae": 0.9813780188560486,
        "Carnivore": 0.8667572736740112,
        "Dog": 0.9953705072402954,
        "Dog breed": 0.9838448762893677,
        "Havanese": 1,
        "Mammal": 0.975814163684845,
        "Puppy": 0.8966773748397827,
        "Schnoodle": 0,
        "Sporting Group": 0.8070302605628967,
        "Vertebrate": 0.9851104021072388
      },
      "uploaded_by": null,
      "uploaded_by_api": false,
      "warning_adult": 1,
      "warning_medical": 1,
      "warning_racy": 1,
      "warning_spoof": 2,
      "warning_violence": 1
    },
    "id": "5b81e81539ddc50001a5d955/luke.jpg",
    "type": "assets"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "authentication": {
      "authorized": true,
      "clientId": null,
      "mode": "PUBLIC_APIKEY",
      "modeTitle": "Public API Key",
      "tag": "cindy@ymail.com",
      "user": null
    },
    "server": {
      "commit": "8835d05b",
      "status": {
        "healthy": true,
        "read_only": false,
        "tombstone": false
      },
      "version": "3.120.0"
    }
  }
}

Updating categories and custom fields of an asset

PATCH /api/v1/assets/5b81e81539ddc50001a5d955/luke.jpg
 
{
  "data": {
    "attributes": {
      "categories": [
        "Summer Photos",
        "Pet Photos"
       ],
       "custom_fields": {
         "Date taken": "August 2020",
         "Photographer": "Molly"
       }
    },
    "type": "assets",
     "id": "5b81e81539ddc50001a5d955/luke.jpg"
    }
}
{
  "data": {
    "attributes": {
      "categories": [
        "Summer Photos",
        "Pet Photos"
       ],
       ...
       "custom_fields": {
         "Date taken": "August 2020",
         "Photographer": "Molly"
       },
       ...
    }
    ...
 }

Retrieving the second page of assets in a Source

GET /api/v1/assets/5b81e81539ddc50001a5d955?page[cursor]=40&page[limit]=20
{
  "data": [
     ...
   ],
   ...
   "cursor": {
     "current": "40",
     "estimatedRecords": null,
     "hasMore": true,
     "next": "60",
     "totalRecords": null
    }
    ...
}

Retrieving assets, filtered by color and sorted by date created, most recent first

GET /api/v1/assets/5b81e81539ddc50001a5d955?filter[colors]=8ca091&sort=-date_created
{
  "data": [
    {
      "attributes": {
      ...
        "colors": {
          "dominant_colors": {
            "#1b181a": 0.08416759222745895,
            "#343235": 0.09766407310962677,
            "#535153": 0.059176862239837646,
            "#a32438": 0.00037078236346133053,
            "#a49d97": 0.039377085864543915,
            "#b19f89": 0.05094549432396889,
            "#c8c1ba": 0.06518353521823883,
            "#d0bfa9": 0.10700778663158417,
            "#efe2cf": 0.06436781585216522,
            "#f7f3ee": 0.2693363130092621
          }
        },
        "content_type": "image/png",
        "custom_fields": null,
        "date_created": 1589337592,
	...
      },
      "id": "5b81e81539ddc50001a5d955/images/frances.jpg",
      "type": "assets"
    },
    {
      "attributes": {
      ...
        "colors": {
          "dominant_colors": {
            "#160802": 0.11790844798088074,
            "#230a03": 0.009009009227156639,
            "#2f1104": 0.04248843342065811,
            "#6a5340": 0.04790601506829262,
            "#6e4a36": 0.07487216591835022,
            "#8b6c5a": 0.010409058071672916,
            "#907864": 0.11200389266014099,
            "#a4958c": 0.011626491323113441,
            "#af967f": 0.1546749472618103,
            "#c4ae97": 0.0022522523067891598
          }
        },
        "content_type": "image/jpeg",
        "custom_fields": null,
        "date_created": 1587358372,
    	...
      },
      "id": "5b81e81539ddc50001a5d955/images/luke.jpg",
      "type": "assets"
    },
    ...
  ],
  ...
}
 

Uploading an asset to a Source

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload/marketing/logo.png
 
<raw binary image file>
{
  "data": {
    "attributes": {
      ...
      "origin_path": "/marketing/logo.png",
      "tags": {
        "Brand": 0.772368848323822,
        "Clip art": 0.5367497801780701,
        "Font": 0.9227379560470581,
        "Graphics": 0.7015061974525452,
        "Line": 0.7984547019004822,
        "Logo": 0.9082068800926208,
        "Text": 0.9606743454933167,
        "Trademark": 0.7562870383262634
      },
      ...
    },
    "id": "5b81e81539ddc50001a5d955/marketing/logo.png",
    "type": "assets"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
   ...
  }
}

Creating an upload session

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/create/marketing/logo.png
{
  "data": {
    "attributes": {
      "date_created": 1653506429,
      "date_expires": 1653535229,
      "date_modified": 1653506429,
      "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
      "origin_path": "/marketing/logo.png",
      "source_id": "5b81e81539ddc50001a5d955",
      "status": "PENDING",
      "url": "$PRESIGNED_UPLOAD_URL"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Using the presigned URL to upload an asset, using the url from the newly created upload session

curl -XPUT $PRESIGNED_URL -T 'image.jpg'

Retrieving an upload session

GET /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/status/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      "date_created": 1653506429,
      "date_expires": 1653535229,
      "date_modified": 1653506429,
      "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
      "origin_path": "/marketing/logo.png",
      "source_id": "5b81e81539ddc50001a5d955",
      "status": "PENDING"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Closing an upload session

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/close/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      ...
      "status": "CLOSED"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Canceling an upload session

DELETE /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/cancel/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      ...
      "status": "CANCELED"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}