upload-files

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Upload Files to ImageKit

向ImageKit上传文件

CRITICAL: Only URL-based uploads are supported

关键注意事项：仅支持基于URL的上传

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

file

参数必须是可公开访问的URL字符串。无法上传本地文件——本地路径、Buffer和流均不支持，会导致上传失败。如果用户拥有本地文件，必须先将其托管到可公开访问的URL，再传入该URL。

file

和

fileName

均为必填项。

切勿将本地文件转换为base64（数据URI）字符串尝试上传。将文件读取到模型上下文进行base64编码会消耗大量LLM令牌，且大文件仍无法上传。始终传入URL——绝不直接嵌入文件字节。

上传操作通过

mcp_imagekit_api_execute

调用SDK的

client.files.upload()

方法完成。

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

typescript

async function run(client) {
  const file = await client.files.upload({
    file: 'https://example.com/photo.jpg', // 仅支持URL字符串——不允许本地路径
    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

参数名称与Upload API（

FileUploadV1

）的字段名称一致，采用小驼峰命名法。若省略字段，ImageKit将应用其默认值。

参数	说明
`file` （必填）	待上传文件的可公开访问URL。不允许使用本地路径。
`fileName` （必填）	上传后的文件名，例如 `'photo.jpg'` 。
`folder`	ImageKit中的目标文件夹（默认值： `/` ）
`tags`	标签数组（例如 `['product', 'featured']` ）
`isPrivateFile`	将文件标记为私有
`isPublished`	发布文件；设为 `false` 则以上草稿形式上传（仅企业版可用）
`useUniqueFileName`	为文件名添加唯一后缀（默认值 `true` ）
`overwriteFile`	覆盖同一路径下的现有文件
`overwriteAITags`	替换文件时覆盖现有AITags
`overwriteTags`	替换文件时覆盖现有标签
`overwriteCustomMetadata`	替换文件时覆盖现有自定义元数据
`description`	文件描述
`customCoordinates`	重点区域： `"x,y,width,height"`
`customMetadata`	自定义元数据对象，例如 `{ brand: 'Nike' }` （字段需先在DAM中创建）
`extensions`	扩展功能数组，例如 `[{ name: 'google-auto-tagging', maxTags: 5 }]`
`transformation`	预处理/后处理转换配置，例如 `{ pre: 'w-1200,q-80' }`
`webhookUrl`	接收扩展功能完成状态的URL
`responseFields`	响应中需包含的字段（例如 `['tags', 'customMetadata', 'metadata']` ）
`checks`	服务器端上传校验表达式

Examples

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.

无法上传本地文件：仅可使用可公开访问的URL。若用户提供本地路径，请告知其先将文件托管到公开地址并提供URL。
```
folder
```
是ImageKit媒体库中的路径（非本地路径）。以
```
/
```
开头，会自动创建嵌套文件夹。请勿在文件夹路径中包含文件名。
```
fileName
```
允许使用：
```
a-z
```
、
```
A-Z
```
、
```
0-9
```
、
```
.
```
、
```
-
```
。其他字符会被替换为
```
_
```
。
```
useUniqueFileName
```
默认值为
```
true
```
（会追加唯一后缀）。若要覆盖同名文件，请设置
```
useUniqueFileName: false
```
并开启
```
overwriteFile: true
```
。
```
customMetadata
```
的字段需先在DAM中创建。

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

获取公开URL：确认文件可通过公开URL访问。若用户仅有本地文件，请暂停操作并要求其先托管文件并提供URL。
确定文件夹与标签：指定文件在ImageKit媒体库中的存储位置及标签。

执行上传：通过

mcp_imagekit_api_execute

调用

client.files.upload()

完成上传。

验证响应：确认返回结果包含
```
fileId
```
和
```
url
```
，且
```
size
```
/
```
fileType
```
与预期匹配（图片的
```
fileType
```
为
```
image
```
，视频及其他文件为
```
non-image
```
）。

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.

本地路径会导致失败：不支持传入本地文件路径、Buffer或流——始终传入URL字符串。
绝不要通过base64编码上传文件：将本地文件转换为base64/数据URI字符串会浪费LLM令牌，且大文件无法上传。请先托管文件再传入其URL。
文件大小限制：免费版：图片最大25MB，视频最大100MB。付费版限制更高。
版本限制：每个文件最多支持100个版本。