Media API

ImageKit.io allows you to manage media assets programmatically. All the functionality exposed in the ImageKit dashboard is available via APIs. You can integrate these APIs in your CMS to achieve any integration you can imagine.
​Listing and searching assets - Search existing assets in the Media library by the combination of multiple asset attributes e.g., name, location, associated tags, embedded and custom metadata associated with the asset.
​Updating asset - Updating tags, adding custom coordinates for cropping, applying background removal extension, updating tags using machine learning, or updating associated custom metadata with the asset.
​Getting individual file details. - Get details of an individual current file.
​Getting individual file version details. - Get details of an individual file version.
​Get file versions. - Get details of all versions of a file.
​Deleting assets.
​Delete assets in bulk.
​Delete file version. - Delete a non-current version of a file.
​Restore file version. - Restore to a non-current version of a file.
​Purging cache on CDN.
​Getting image metadata for an image file.
Bulk add or remove user added tags.
Bulk remove AI tags.
​Copy, move and rename assets.
​Create, copy, move, and delete folder.
​Get bulk job status for copy and move folder jobs.
All media APIs accept JSON-encoded request bodies and return JSON-encoded responses.
File object structure
1
{
2
    "type": "file",
3
    "name": "sample-car.jpeg",
4
    "createdAt": "2021-12-11T00:58:39.685Z",
5
    "updatedAt": "2022-05-19T10:57:07.511Z",
6
    "fileId": "61b3f7bf75889b0b19970117",
7
    "tags": [
8
        "luxury"
9
    ],
10
    "AITags": [
11
        {
12
            "name": "Wheel",
13
            "confidence": 95.44,
14
            "source": "google-auto-tagging"
15
        },
16
        {
17
            "name": "Tire",
18
            "confidence": 94.22,
19
            "source": "google-auto-tagging"
20
        },
21
        {
22
            "name": "Vehicle",
23
            "confidence": 93.95,
24
            "source": "google-auto-tagging"
25
        },
26
        {
27
            "name": "Hood",
28
            "confidence": 91.83,
29
            "source": "google-auto-tagging"
30
        },
31
        {
32
            "name": "Grille",
33
            "confidence": 91.77,
34
            "source": "google-auto-tagging"
35
        },
36
        {
37
            "name": "Car",
38
            "confidence": 99.87,
39
            "source": "aws-auto-tagging"
40
        },
41
        {
42
            "name": "Tire",
43
            "confidence": 98.93,
44
            "source": "aws-auto-tagging"
45
        },
46
        {
47
            "name": "Sports Car",
48
            "confidence": 98.85,
49
            "source": "aws-auto-tagging"
50
        },
51
        {
52
            "name": "Wheel",
53
            "confidence": 98.46,
54
            "source": "aws-auto-tagging"
55
        },
56
        {
57
            "name": "Coupe",
58
            "confidence": 97.82,
59
            "source": "aws-auto-tagging"
60
        }
61
    ],
62
    "versionInfo": {
63
        "id": "61b3f7bf75889b0b19970117",
64
        "name": "Version 1"
65
    },
66
    "embeddedMetadata": null,
67
    "customCoordinates": null,
68
    "customMetadata": {},
69
    "isPrivateFile": false,
70
    "url": "https://ik.imagekit.io/demo/sample-car.jpeg",
71
    "thumbnail": "https://ik.imagekit.io/demo/tr:n-ik_ml_thumbnail/sample-car.jpeg",
72
    "fileType": "image",
73
    "filePath": "/sample-car.jpeg",
74
    "height": 638,
75
    "width": 1342,
76
    "size": 1451076,
77
    "hasAlpha": true,
78
    "mime": "image/png"
79
}
Copied!
Property name
Description
fileId
The unique fileId of the uploaded file. All versions of a file will have the same fileId associated with it.
type
Type of item. It can be file or folder.
name
Name of the file.
filePath
The relative path of the file. In the case of an image, you can use this path to construct different transformations.
tags
The array of tags associated with the image. If no tags are set, it will be null.
AITags
Array of AITags associated with the image. If no AITags are set, it will be null. These tags can be added using the google-auto-tagging or aws-auto-tagging extensions.
versionInfo
An object containing the file or file version's id (versionId) and name.
isPrivateFile
Is the file marked as private. It can be either true or false.
customCoordinates
Value of custom coordinates associated with the image in the format x,y,width,height. If customCoordinates are not defined, then it is null.

url
A publicly accessible URL of the file.
thumbnail
In the case of an image, a small thumbnail URL.
fileType
The type of file could be either image or non-image.
mime
MIME Type of the file. For example - image/jpeg
height
Height of the image in pixels (Only for images)
width
Width of the image in pixels (Only for Images)
size
Size of the image file in Bytes
hasAlpha
A boolean indicating if the image has an alpha layer or not.
customMetadata
A key-value data associated with the asset. Before setting any custom metadata on an asset, you have to create the field using custom metadata fields API.
embeddedMetadata
Consolidated embedded metadata associated with the file. It includes exif, iptc, and xmp data.
createdAt
The date and time when the file was first uploaded. The format is YYYY-MM-DDTHH:mm:ss.sssZ
Embedded metadata object structure
Below is the embedded metadata stored in this sample image provided by https://iptc.org.
1
{
2
    ExifVersion: '0232',
3
    ImageDescription: 'The description aka caption (ref2019.1)',
4
    XResolution: 72,
5
    YResolution: 72,
6
    ResolutionUnit: 'inches',
7
    Artist: 'Creator1 (ref2019.1)',
8
    Copyright: 'Copyright (Notice) 2019.1 IPTC - www.iptc.org  (ref2019.1)',
9
    DateTimeOriginal: new Date('2019-10-16T19:01:03.000Z'),
10
    OffsetTimeOriginal: '+00:00',
11
    ComponentsConfiguration: 'Y,Cb,Cr,-',
12
    FlashpixVersion: '0100',
13
    ColorSpace: 'Uncalibrated',
14
    ObjectAttributeReference: 'A Genre (ref2019.1)',
15
    ObjectName: 'The Title (ref2019.1)',
16
    SubjectReference: ['IPTC:1ref2019.1', 'IPTC:2ref2019.1', 'IPTC:3ref2019.1'],
17
    Keywords: ['Keyword1ref2019.1', 'Keyword2ref2019.1', 'Keyword3ref2019.1'],
18
    SpecialInstructions: 'An Instruction (ref2019.1)',
19
    TimeCreated: '19:01:03+00:00',
20
    Byline: 'Creator1 (ref2019.1)',
21
    BylineTitle: "Creator's Job Title  (ref2019.1)",
22
    Sublocation: 'Sublocation (Core) (ref2019.1)',
23
    ProvinceState: 'Province/State(Core)(ref2019.1)',
24
    CountryPrimaryLocationCode: 'R19',
25
    CountryPrimaryLocationName: 'Country (Core) (ref2019.1)',
26
    OriginalTransmissionReference: 'Job Id (ref2019.1)',
27
    CopyrightNotice: 'Copyright (Notice) 2019.1 IPTC - www.iptc.org  (ref2019.1)',
28
    CaptionAbstract: 'The description aka caption (ref2019.1)',
29
    WriterEditor: 'Description Writer (ref2019.1)',
30
    ApplicationRecordVersion: 4,
31
    CountryCode: 'R19',
32
    CreatorCity: "Creator's CI: City (ref2019.1)",
33
    CreatorCountry: "Creator's CI: Country (ref2019.1)",
34
    CreatorAddress: "Creator's CI: Address, line 1 (ref2019.1)",
35
    CreatorPostalCode: "Creator's CI: Postcode (ref2019.1)",
36
    CreatorRegion: "Creator's CI: State/Province (ref2019.1)",
37
    CreatorWorkEmail: "Creator's CI: [email protected], [email protected] (ref2019.1)",
38
    CreatorWorkTelephone: "Creator's CI: Phone # 1, Phone # 2 (ref2019.1)",
39
    CreatorWorkURL: 'http://www.Creators.CI/WebAddress/ref2019.1',
40
    IntellectualGenre: 'A Genre (ref2019.1)',
41
    Location: 'Sublocation (Core) (ref2019.1)',
42
    Scene: ['IPTC-Scene-Code1 (ref2019.1)', 'IPTC-Scene-Code2 (ref2019.1)'],
43
    SubjectCode: ['IPTC:1ref2019.1', 'IPTC:2ref2019.1', 'IPTC:3ref2019.1'],
44
    AboutCvTermCvId: 'http://example.com/cv/about/ref2019.1',
45
    AboutCvTermId: 'http://example.com/cv/about/ref2019.1/code987',
46
    AboutCvTermName: 'CV-Term Name 1 (ref2019.1)',
47
    AboutCvTermRefinedAbout: 'http://example.com/cv/refinements2/ref2019.1/codeX145',
48
    AdditionalModelInformation: 'Additional Model Info (ref2019.1)',
49
    ArtworkCircaDateCreated: 'AO Circa Date: between 1550 and 1600 (ref2019.1)',
50
    ArtworkContentDescription: 'AO Content Description 1 (ref2019.1)',
51
    ArtworkContributionDescription: 'AO Contribution Description 1 (ref2019.1)',
52
    ArtworkCopyrightNotice: 'AO Copyright Notice 1 (ref2019.1)',
53
    ArtworkCreator: [
54
      'AO Creator Name 1a (ref2019.1)',
55
      'AO Creator Name 1b (ref2019.1)'
56
    ],
57
    ArtworkCreatorID: ['AO Creator Id 1a (ref2019.1)', 'AO Creator Id 1b (ref2019.1)'],
58
    ArtworkCopyrightOwnerID: 'AO Current Copyright Owner ID 1 (ref2019.1)',
59
    ArtworkCopyrightOwnerName: 'AO Current Copyright Owner Name 1 (ref2019.1)',
60
    ArtworkLicensorID: 'AO Current Licensor ID 1 (ref2019.1)',
61
    ArtworkLicensorName: 'AO Current Licensor Name 1 (ref2019.1)',
62
    ArtworkDateCreated: new Date('1919-10-16T19:01:00.000Z'),
63
    ArtworkPhysicalDescription: 'AO Physical Description 1 (ref2019.1)',
64
    ArtworkSource: 'AO Source 1 (ref2019.1)',
65
    ArtworkSourceInventoryNo: 'AO Source Inventory No 1 (ref2019.1)',
66
    ArtworkSourceInvURL: 'AO Source Inventory URL (ref2019.1)',
67
    ArtworkStylePeriod: [
68
      'AO Style Baroque (ref2019.1)',
69
      'AO Style Italian Baroque (ref2019.1)'
70
    ],
71
    ArtworkTitle: 'AO Title 1 (ref2019.1)',
72
    DigitalImageGUID: 'http://example.com/imageGUIDs/TestGUID12345/ref2019.1',
73
    DigitalSourceType: 'http://cv.iptc.org/newscodes/digitalsourcetype/softwareImage',
74
    EmbeddedEncodedRightsExpr: 'The Encoded Rights Expression (ref2019.1)',
75
    EmbeddedEncodedRightsExprType: 'IANA Media Type of ERE (ref2019.1)',
76
    EmbeddedEncodedRightsExprLangID: 'http://example.org/RELids/id4711/ref2019.1',
77
    Event: 'An Event (ref2019.1)',
78
    GenreCvId: 'http://example.com/cv/genre/ref2019.1',
79
    GenreCvTermId: 'http://example.com/cv/genre/ref2019.1/code1369',
80
    GenreCvTermName: 'Genre CV-Term Name 1 (ref2019.1)',
81
    GenreCvTermRefinedAbout: 'http://example.com/cv/genrerefinements2/ref2019.1/codeY864',
82
    ImageRegionName: ['Listener 1', 'Listener 2', 'Speaker 1'],
83
    ImageRegionOrganisationInImageName: [
84
      'Organisation name no 1 in region persltr2 (ref2019.1)',
85
      'Organisation name no 1 in region persltr2 (ref2019.1)',
86
      'Organisation name no 1 in region persltr3 (ref2019.1)'
87
    ],
88
    ImageRegionPersonInImage: [
89
      'Person name no 1 in region persltr2 (ref2019.1)',
90
      'Person name no 1 in region persltr3 (ref2019.1)',
91
      'Person name no 1 in region persltr1 (ref2019.1)'
92
    ],
93
    ImageRegionBoundaryH: [0.385],
94
    ImageRegionBoundaryShape: ['rectangle', 'circle', 'polygon'],
95
    ImageRegionBoundaryUnit: ['relative', 'relative', 'relative'],
96
    ImageRegionBoundaryW: [0.127],
97
    ImageRegionBoundaryX: [0.31, 0.59],
98
    ImageRegionBoundaryY: [0.18, 0.426],
99
    ImageRegionCtypeName: [
100
      'Region Boundary Content Type Name (ref2019.1)',
101
      'Region Boundary Content Type Name (ref2019.1)',
102
      'Region Boundary Content Type Name (ref2019.1)'
103
    ],
104
    ImageRegionCtypeIdentifier: [
105
      'https://example.org/rctype/type2019.1a',
106
      'https://example.org/rctype/type2019.1b',
107
      'https://example.org/rctype/type2019.1a',
108
      'https://example.org/rctype/type2019.1b',
109
      'https://example.org/rctype/type2019.1a',
110
      'https://example.org/rctype/type2019.1b'
111
    ],
112
    ImageRegionID: ['persltr2', 'persltr3', 'persltr1'],
113
    ImageRegionRoleName: [
114
      'Region Boundary Content Role Name (ref2019.1)',
115
      'Region Boundary Content Role Name (ref2019.1)',
116
      'Region Boundary Content Role Name (ref2019.1)'
117
    ],
118
    ImageRegionRoleIdentifier: [
119
      'https://example.org/rrole/role2019.1a',
120
      'https://example.org/rrole/role2019.1b',
121
      'https://example.org/rrole/role2019.1a',
122
      'https://example.org/rrole/role2019.1b',
123
      'https://example.org/rrole/role2019.1a',
124
      'https://example.org/rrole/role2019.1b'
125
    ],
126
    ImageRegionBoundaryRx: [0.068],
127
    ImageRegionBoundaryVerticesX: [0.05, 0.148, 0.375],
128
    ImageRegionBoundaryVerticesY: [0.713, 0.041, 0.863],
129
    LinkedEncodedRightsExpr: 'http://example.org/linkedrightsexpression/id986/ref2019.1',
130
    LinkedEncodedRightsExprType: 'IANA Media Type of ERE (ref2019.1)',
131
    LinkedEncodedRightsExprLangID: 'http://example.org/RELids/id4712/ref2019.1',
132
    LocationCreatedCity: 'City (Location created1) (ref2019.1)',
133
    LocationCreatedCountryCode: 'R17',
134
    LocationCreatedCountryName: 'CountryName (Location created1) (ref2019.1)',
135
    LocationCreatedLocationId: 'Location Id (Location created1) (ref2019.1)',
136
    LocationCreatedLocationName: 'Location Name (Location created1) (ref2019.1)',
137
    LocationCreatedProvinceState: 'Province/State (Location created1) (ref2019.1)',
138
    LocationCreatedSublocation: 'Sublocation (Location created1) (ref2019.1)',
139
    LocationCreatedWorldRegion: 'Worldregion (Location created1) (ref2019.1)',
140
    LocationCreatedGPSAltitude: '480 m',
141
    LocationCreatedGPSLatitude: '48,16.5N',
142
    LocationCreatedGPSLongitude: '16,20.28E',
143
    LocationShownCity: [
144
      'City (Location shown1) (ref2019.1)',
145
      'City (Location shown2) (ref2019.1)'
146
    ],
147
    LocationShownCountryCode: ['R17', 'R17'],
148
    LocationShownCountryName: [
149
      'CountryName (Location shown1) (ref2019.1)',
150
      'CountryName (Location shown2) (ref2019.1)'
151
    ],
152
    LocationShownLocationId: [
153
      'Location Id 1a(Location shown1) (ref2019.1)',
154
      'Location Id 1b(Location shown1) (ref2019.1)',
155
      'Location Id 2a(Location shown2) (ref2019.1)',
156
      'Location Id 2b(Location shown2) (ref2019.1)'
157
    ],
158
    LocationShownLocationName: [
159
      'Location Name (Location shown1) (ref2019.1)',
160
      'Location Name (Location shown2) (ref2019.1)'
161
    ],
162
    LocationShownProvinceState: [
163
      'Province/State (Location shown1) (ref2019.1)',
164
      'Province/State (Location shown2) (ref2019.1)'
165
    ],
166
    LocationShownSublocation: [
167
      'Sublocation (Location shown1) (ref2019.1)',
168
      'Sublocation (Location shown2) (ref2019.1)'
169
    ],
170
    LocationShownWorldRegion: [
171
      'Worldregion (Location shown1) (ref2019.1)',
172
      'Worldregion (Location shown2) (ref2019.1)'
173
    ],
174
    LocationShownGPSAltitude: ['140 m', '120 m'],
175
    LocationShownGPSLatitude: ['48,8.82N', '47,57.12N'],
176
    LocationShownGPSLongitude: ['17,5.88E', '16,49.8E'],
177
    MaxAvailHeight: 20,
178
    MaxAvailWidth: 19,
179
    ModelAge: [25, 27, 30],
180
    OrganisationInImageCode: [
181
      'Organisation Code 1 (ref2019.1)',
182
      'Organisation Code 2 (ref2019.1)',
183
      'Organisation Code 3 (ref2019.1)'
184
    ],
185
    OrganisationInImageName: [
186
      'Organisation Name 1 (ref2019.1)',
187
      'Organisation Name 2 (ref2019.1)',
188
      'Organisation Name 3 (ref2019.1)'
189
    ],
190
    PersonInImage: ['Person Shown 1 (ref2019.1)', 'Person Shown 2 (ref2019.1)'],
191
    PersonInImageCvTermCvId: ['http://example.com/cv/test99/ref2019.1'],
192
    PersonInImageCvTermId: ['http://example.com/cv/test99/code987/ref2019.1'],
193
    PersonInImageCvTermName: ['Person Characteristic Name 1 (ref2019.1)'],
194
    PersonInImageCvTermRefinedAbout: ['http://example.com/cv/refinements987/codeY765/ref2019.1'],
195
    PersonInImageDescription: ['Person Description 1 (ref2019.1)'],
196
    PersonInImageId: [
197
      'http://wikidata.org/item/Q123456789/ref2019.1',
198
      'http://freebase.com/m/987654321/ref2019.1'
199
    ],
200
    PersonInImageName: ['Person Name 1 (ref2019.1)'],
201
    ProductInImageDescription: ['Product Description 1 (ref2019.1)'],
202
    ProductInImageGTIN: [123456782019.1],
203
    ProductInImageName: ['Product Name 1 (ref2019.1)'],
204
    RegistryEntryRole: [
205
      'Registry Entry Role ID 1 (ref2019.1)',
206
      'Registry Entry Role ID 2 (ref2019.1)'
207
    ],
208
    RegistryItemID: [
209
      'Registry Image ID 1 (ref2019.1)',
210
      'Registry Image ID 2 (ref2019.1)'
211
    ],
212
    RegistryOrganisationID: [
213
      'Registry Organisation ID 1 (ref2019.1)',
214
      'Registry Organisation ID 2 (ref2019.1)'
215
    ],
216
    Creator: 'Creator1 (ref2019.1)',
217
    Description: 'The description aka caption (ref2019.1)',
218
    Rights: 'Copyright (Notice) 2019.1 IPTC - www.iptc.org  (ref2019.1)',
219
    Subject: ['Keyword1ref2019.1', 'Keyword2ref2019.1', 'Keyword3ref2019.1'],
220
    Title: 'The Title (ref2019.1)',
221
    AuthorsPosition: 'Creator&#39;s Job Title  (ref2019.1)',
222
    CaptionWriter: 'Description Writer (ref2019.1)',
223
    City: 'City (Core) (ref2019.1)',
224
    Country: 'Country (Core) (ref2019.1)',
225
    Credit: 'Credit Line (ref2019.1)',
226
    DateCreated: new Date('2019-10-16T19:01:03.000Z'),
227
    Headline: 'The Headline (ref2019.1)',
228
    Instructions: 'An Instruction (ref2019.1)',
229
    Source: 'Source (ref2019.1)',
230
    State: 'Province/State(Core)(ref2019.1)',
231
    TransmissionReference: 'Job Id (ref2019.1)',
232
    CopyrightOwnerID: [
233
      'Copyright Owner Id 1 (ref2019.1)',
234
      'Copyright Owner Id 2 (ref2019.1)'
235
    ],
236
    CopyrightOwnerName: [
237
      'Copyright Owner Name 1 (ref2019.1)',
238
      'Copyright Owner Name 2 (ref2019.1)'
239
    ],
240
    ImageCreatorID: 'Image Creator Id 1 (ref2019.1)',
241
    ImageCreatorName: 'Image Creator Name 1 (ref2019.1)',
242
    ImageCreatorImageID: 'Image Creator Image ID (ref2019.1)',
243
    ImageSupplierID: 'Image Supplier Id (ref2019.1)',
244
    ImageSupplierName: 'Image Supplier Name (ref2019.1)',
245
    ImageSupplierImageID: 'Image Supplier Image ID (ref2019.1)',
246
    LicensorCity: ['Licensor City 1 (ref2019.1)', 'Licensor City 2 (ref2019.1)'],
247
    LicensorCountry: [
248
      'Licensor Country 1 (ref2019.1)',
249
      'Licensor Country 2 (ref2019.1)'
250
    ],
251
    LicensorEmail: ['Licensor Email 1 (ref2019.1)', 'Licensor Email 2 (ref2019.1)'],
252
    LicensorExtendedAddress: [
253
      'Licensor Ext Addr 1 (ref2019.1)',
254
      'Licensor Ext Addr 2 (ref2019.1)'
255
    ],
256
    LicensorID: ['Licensor ID 1 (ref2019.1)', 'Licensor ID 2 (ref2019.1)'],
257
    LicensorName: ['Licensor Name 1 (ref2019.1)', 'Licensor Name 2 (ref2019.1)'],
258
    LicensorPostalCode: [
259
      'Licensor Postcode 1 (ref2019.1)',
260
      'Licensor Postcode 2 (ref2019.1)'
261
    ],
262
    LicensorRegion: ['Licensor Region 1 (ref2019.1)', 'Licensor Region 2 (ref2019.1)'],
263
    LicensorStreetAddress: [
264
      'Licensor Street Addr 1 (ref2019.1)',
265
      'Licensor Street Addr 2 (ref2019.1)'
266
    ],
267
    LicensorTelephone1: ['Licensor Phone1 1 (ref2019.1)', 'Licensor Phone1 2 (ref2019.1)'],
268
    LicensorTelephone2: ['Licensor Phone2 1 (ref2019.1)', 'Licensor Phone2 2 (ref2019.1)'],
269
    LicensorURL: ['Licensor URL 1 (ref2019.1)', 'Licensor URL 2 (ref2019.1)'],
270
    ModelReleaseID: [
271
      'Model Release ID 1 (ref2019.1)',
272
      'Model Release ID 2 (ref2019.1)'
273
    ],
274
    PropertyReleaseID: [
275
      'Property Release ID 1 (ref2019.1)',
276
      'Property Release ID 2 (ref2019.1)'
277
    ],
278
    Rating: 1,
279
    UsageTerms: 'Rights Usage Terms (ref2019.1)',
280
    WebStatement: 'http://www.WebStatementOfRights.org/2019.1',
281
    DateTimeCreated: new Date('2019-10-16T19:01:03.000Z'),
282
    Caption: 'The description aka caption (ref2019.1)',
283
    Writer: 'Description Writer (ref2019.1)'
284
  }
Copied!
Client side file upload
List and search files
Last modified 1mo ago
Copy link
Contents
File object structure
Embedded metadata object structure