upload-files

Original：🇺🇸 English

Translated

Upload files to ImageKit from a publicly accessible URL. Use when: uploading images, videos, or files to ImageKit media library; specifying folder paths; setting file names, tags, or metadata during upload. NOTE: only URL-based uploads are supported — local file paths cannot be passed.

1installs

Sourceimagekit-developer/skills

Added on2026-08-11

NPX Install

npx skill4agent add imagekit-developer/skills upload-files

SKILL.md Content

View Translation Comparison →

Upload Files to ImageKit

CRITICAL: Only URL-based uploads are supported

The

file

parameter must be a publicly accessible URL string. Local files cannot be uploaded — local paths, Buffers, and streams are not supported and will fail. If the user has a local file, they must first host it at a public URL and pass that URL.

Both

file

and

fileName

are required.

NEVER convert a local file to a base64 (data URI) string and try to upload it. Reading a file into the model context to base64-encode it burns a huge number of LLM tokens and still won't work for large files. Always pass a URL — never inline file bytes.

Uploads are performed with the SDK's

client.files.upload()

method via

mcp_imagekit_api_execute

Usage

typescript

async function run(client) {
  const file = await client.files.upload({
    file: 'https://example.com/photo.jpg', // URL string ONLY — no local paths
    fileName: 'photo.jpg',
    folder: '/products',
    tags: ['product', 'featured'],
  });
  return { fileId: file.fileId, url: file.url, size: file.size, fileType: file.fileType };
}

Parameters

Parameter names mirror the Upload API (

FileUploadV1

) field names in camelCase. When a field is omitted, ImageKit applies its own default.

Parameter	Description
`file` (required)	Publicly accessible URL of the file to upload. Local paths are NOT allowed.
`fileName` (required)	Name for the uploaded file, e.g. `'photo.jpg'` .
`folder`	Destination folder in ImageKit (default: `/` )
`tags`	Array of tags (e.g. `['product', 'featured']` )
`isPrivateFile`	Mark file as private
`isPublished`	Publish the file; `false` uploads as draft (enterprise plans)
`useUniqueFileName`	Add a unique suffix to the filename (default `true` )
`overwriteFile`	Overwrite an existing file at the same path
`overwriteAITags`	Overwrite existing AITags when replacing
`overwriteTags`	Overwrite existing tags when replacing
`overwriteCustomMetadata`	Overwrite existing customMetadata when replacing
`description`	Description for the file
`customCoordinates`	Important area: `"x,y,width,height"`
`customMetadata`	Object of custom metadata, e.g. `{ brand: 'Nike' }` (fields must exist in DAM first)
`extensions`	Array of extensions, e.g. `[{ name: 'google-auto-tagging', maxTags: 5 }]`
`transformation`	Object of pre/post transformations, e.g. `{ pre: 'w-1200,q-80' }`
`webhookUrl`	URL to receive extension completion status
`responseFields`	Fields to include in the response (e.g. `['tags', 'customMetadata', 'metadata']` )
`checks`	Server-side upload check expression

Examples

typescript

// Basic upload to a folder with tags
await client.files.upload({
  file: 'https://example.com/photo.jpg',
  fileName: 'photo.jpg',
  folder: '/products',
  tags: ['product', 'featured'],
});

// Overwrite an exact-named file
await client.files.upload({
  file: 'https://example.com/banner.jpg',
  fileName: 'banner.jpg',
  useUniqueFileName: false,
  overwriteFile: true,
});

// Upload with auto-tagging extension
await client.files.upload({
  file: 'https://example.com/photo.jpg',
  fileName: 'photo.jpg',
  extensions: [{ name: 'google-auto-tagging', maxTags: 5 }],
});

// Upload with custom metadata and a pre-transformation
await client.files.upload({
  file: 'https://example.com/photo.jpg',
  fileName: 'photo.jpg',
  customMetadata: { brand: 'Nike' },
  transformation: { pre: 'w-1200,q-80' },
});

Notes

Local files cannot be uploaded. Only a publicly accessible URL works. If the user provides a local path, tell them to host it publicly first and share the URL.
```
folder
```
is the ImageKit media library path (not local). Starts with
```
/
```
, auto-creates nested folders. Don't include the filename in the folder path.
```
fileName
```
allows:
```
a-z
```
,
```
A-Z
```
,
```
0-9
```
,
```
.
```
,
```
-
```
. Other characters become
```
_
```
.
```
useUniqueFileName
```
defaults to
```
true
```
(a unique suffix is appended). To overwrite an exact-named file, set
```
useUniqueFileName: false
```
and
```
overwriteFile: true
```
.
```
customMetadata
```
fields must be created in the DAM first.

Procedure

Get a public URL: Confirm the file is available at a publicly accessible URL. If the user has only a local file, stop and ask them to host it and provide the URL.
Decide folder and tags: Where in the ImageKit media library the file should live.

Run the upload via

mcp_imagekit_api_execute

using

client.files.upload()

Verify the response: Confirm a
```
fileId
```
and
```
url
```
are returned and the reported
```
size
```
/
```
fileType
```
match (
```
fileType
```
is
```
image
```
for images,
```
non-image
```
for video and other files).

Error Prevention

Local paths fail: Passing a local file path, Buffer, or stream is not supported — always pass a URL string.
Never base64-encode a file to upload it: Converting a local file to a base64/data-URI string wastes LLM tokens and fails for large files. Host the file and pass its URL instead.
File size limits: Free plan: 25MB images, 100MB videos. Paid plans: higher.
Version limit: Max 100 versions per file.