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

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

Endpoint	Method	Description
`sources/:source_id/assets`	GET	Retrieve a list of assets from the Source.
`sources/:source_id/assets/:origin_path`	GET	Retrieve details for a single asset in a Source `source_id` by `asset_id`.
`sources/:source_id/assets/:origin_path`	PATCH	Update a single asset.
`sources/:source_id/upload/:origin_path`	POST	Upload a single asset to the `source_id` Source at `origin_path`. See Uploading for more details.
`sources/:source_id/upload-sessions/:origin_path`	POST	Opens an upload session to `origin_path` for uploading larger assets. See Uploading for more details.
`sources/:source_id/upload-sessions/:session_id`	POST	Closes an upload session at `session_id`. See Uploading for more details.
`sources/:source_id/assets/add/:origin_path`	POST	Adds a single asset to the Asset Manager from the origin. Adding an Asset for more details.
`sources/:source_id/assets/refresh/:origin_path`	POST	Refresh, reprocess, and purge a single asset. See Refreshing an Asset for more details.

Asset Filters

Filter	Type	Notes
`categories`	String
`colors`	String	Hex code (minus the `#`, e.g. `8ca091`.
`custom:<key>`	String	If 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_count`	Integer	A 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_frames`	Boolean
`keyword`	String	Searches across multiple pre-determined fields, such as `origin_path`, `name`, `description`, etc. Exact behavior is subject to change.
`media_kind`	String	Type of asset. Possible values: `IMAGE`, `ANIMATION`, `DOCUMENT`, `VECTOR`.
`origin_path`	String
`tags`	String
`warning_adult`	Integer	Accepted 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_medical`	Integer	Behavior is the same as for `warning_adult` above.
`warning_racy`	Integer	Behavior is the same as for `warning_adult` above.
`warning_spoof`	Integer	Behavior is the same as for `warning_adult` above.
`warning_violence`	Integer	Behavior is the same as for `warning_adult` above.

Asset Sorts

date_created
date_modified
file_size

Asset Attributes

Premium Feature

Access to attributes and asset details is currently available for imgix customers on our Premium plans. If you’re interested in this feature, please contact our sales team to get more information.

Field	Type	Updatable?	Description
`analyzed_content_warnings`	Boolean	No	Whether asset has been analyzed for content warnings.
`analyzed_faces`	Boolean	No	Whether asset has been analyzed for the presence of faces.
`analyzed_tags`	Boolean	No	Whether asset has been analyzed in order to generate tags.
`categories`	List	Yes	List of user-added categories to describe or organize the asset (e.g. “Editorial Images” or “Summer Campaign” or “Profile Pictures”.
`color_model`	String	No	Detected color model (e.g. “RGB” or “CMYK”).
`color_profile`	String	No	Detected color profile (e.g. “Apple Wide Color Sharing Profile”).
`colors`	Object	No	Detected 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_type`	String	No	Detected content type of the asset (e.g. `image/jpeg`, `image/gif`). Unsupported or unknown content types may have value `application/octet-stream`.
`custom_fields`	Object	Yes	User-added custom fields and values (e.g. `{ SKU: 1234 }`)
`date_created`	Integer	No	Unix 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_modified`	Integer	No	Unix timestamp of the last time this asset was modified, whether by an end-user or by an automated update.
`description`	String	Yes	User-provided description of asset.
`dpi_height`	Integer	No	DPI of an image’s height.
`dpi_width`	Integer	No	DPI of an image’s width.
`face_count`	Integer	No	Number of faces detected in an image. Only relevant if `analyzed_faces` is true.
`file_size`	Integer	No	Asset size in bytes.
`has_frames`	Boolean	No	`true` if the asset is an animation (video or gif), `false` otherwise.
`media_height`	Integer	No	Pixel height of asset.
`media_kind`	String	No	Type of asset. Possible values: `IMAGE`, `ANIMATION`, `DOCUMENT`, `VECTOR`.
`media_width`	Integer	No	Pixel width of asset.
`name`	String	Yes	User-provided name of asset. Will not change the `origin-path`.
`origin_path`	String	No	Path to the asset relative to the Source’s prefix.
`source_id`	String	No	ID of the Source this asset is associated with.
`tags`	Object	Yes	Machine-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_by`	String	No	ID of the user who uploaded this asset via the Asset Manager UI, if it was uploaded.
`uploaded_by_api`	Boolean	No	`true` if the asset was uploaded via an API request, `false` otherwise.
`video_aspect_ratio`	String	No	Aspect ratio of a video.
`video_audio_channel_layout`	String	No	Audio channel layout of a video.
`video_duration`	Integer	No	Video duration expressed in seconds.
`video_error_message`	String	No	Error message when unable to process video. `null` otherwise.
`video_has_audio`	Boolean	No	`true` if a video has audio, `false` otherwise.
`video_imgix_status`	String	No	Processing status of a video. Possible values: `INIT_SENT`: Video is in transit to transcoder `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_rate`	Float	No	Max stored frame rate of a video
`video_max_stored_resolution`	String	No	Max stored resolution of a video
`video_max_stored_resolution_x`	Integer	No	Max stored width of a video
`video_max_stored_resolution_y`	Integer	No	Max stored height of a video
`video_playback_url`	String	No	Video playback URL
`warning_adult`	Integer	No	Number 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_medical`	Integer	No	Behavior is the same as for `warning_adult` above.
`warning_racy`	Integer	No	Behavior is the same as for `warning_adult` above.
`warning_spoof`	Integer	No	Behavior is the same as for `warning_adult` above.
`warning_violence`	Integer	No	Behavior 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.

There are two ways to upload assets to a Source:

Default Uploading - Recommended for assets less than 30MB in size. Files exceeding 30MB will return a 413 Request Too Large error with HTML content instead of JSON.
Uploading with Upload Sessions - Recommended for assets larger than 30MB, such as videos.

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

Field	Required?	Description
`type`	Yes	Accepted values are `azure`, `gcs`, and `s3`.
`azure_sas_string`	Yes	Required for `azure`-type Sources only. Read more on how to create Azure credentials.
`gcs_access_key`	Yes	Required for `gcs`-type Sources only.
`gcs_secret_key`	Yes	Required for `gcs`-type Sources only. Will not be returned once it is provided. Read more on how to create GCS credentials.
`s3_access_key`	Yes	Required for `s3`-type Sources only.
`s3_secret_key`	Yes	Required 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 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:

Refetch the asset from the origin.
Reprocess the asset if the ETag 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.
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, Google Cloud, DigitalOcean, Cloudflare R2, Wasabi and Linode Storage sources, and supports file sizes up to 5GB.

Upload Session Flow:

Create an upload session. One session should be created per uploaded file. The session and presigned URL will stay open for 8 hours.
Use the session’s presigned URL to perform an HTTP PUT to upload the file
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.
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": {
    ...
  }
}

General Usage Purges