upload-files

上传文件

上传通过 DAM（https://imagekit.io/mcp/dam）进行。

切勿将文件字节放入对话或工具参数中。 不要使用 base64、数据 URI、Buffers 或流。这会消耗大量令牌，并且处理大文件时会失败。

上传如何运作

上传是向 ImageKit 的上传端点发送 multipart/form-data POST 请求，并使用短期有效、单次使用的签名进行授权。DAM 服务只负责签名。文件会从其所在位置直接发送到 ImageKit：本地文件从用户的机器上传，公共 URL 则由 ImageKit 获取。你的任务是为每个文件获取签名，并确保 POST 请求在文件所在的位置执行。

使用哪个工具

情况	调用
你可以在用户的环境中运行 shell 命令（一个或多个文件、本地路径或公共 URL）	create_upload_signatures_in_bulk，然后运行返回的 uploadCommand。
没有 shell，且用户想在自己的电脑上选择文件（客户端可以显示 MCP Apps）	不带任何参数调用 upload_file。打开文件选择器（文件名、文件夹、标签、自定义元数据）。
用户会在其他地方自行运行上传，并需要签名的表单字段	调用 create_upload_signature；用户使用其 formFields 为每个文件发送 POST 请求。

只要有 shell，就优先使用 create_upload_signatures_in_bulk，即使只有一个文件也如此：签名令牌不会进入对话，一个命令即可上传所有文件，并为每个文件报告状态行。

create_upload_signatures_in_bulk

• 一次调用可为 1 到 1,000 个条目签名。每个条目可以是本地目录中直接包含的文件，也可以是公共 URL，并且各自具有 fileName、folder 和上传字段。
• 不会返回令牌。令牌会留在 manifestUrl 指向的服务器上，直到 expire 时限结束（60 到 3,600 秒，默认 600 秒）。传入 localDirectory，以便命令知道本地文件的位置。
• 在用户的 shell 中运行返回的 uploadCommand。该命令会切换到本地目录、获取清单，并同时上传最多 16 个文件。
• 每个文件会打印一行：<status> <name>。200 表示已上传。SKIP <name> 表示文件名在本地被拒绝（为空、包含 / 或 "，或以 . 开头）。
• 过期前，重新运行同一命令会重试失败的文件。已上传的文件会被拒绝，不会重复上传。过期后会打印 manifest unavailable，且不会上传任何文件，此时需要重新签名。
• 将清单 URL 视为凭据：任何拥有该 URL 的人都可以在过期前上传签名所涵盖的文件。除了命令以外，不要将其粘贴到任何地方。

create_upload_signature

适用于用户自行运行上传（使用自己的脚本或另一台机器）的情况。结果包含签名令牌。

• 一次调用可以为多个文件签名：每个文件发送一个条目，包含 fileName，并可选包含 folder、tags、customMetadata 及其他上传字段。expire 对所有文件生效。
• 结果包含 uploadUrl，并为每个文件提供 formFields：与其签名绑定的确切字段，包括 token。
• 每个文件都要向 uploadUrl 发送 POST 请求，使用 file=@<LOCAL_FILE_PATH>，或者使用 file=<PUBLIC_URL> 让 ImageKit 获取文件，并且附上该文件原样返回的 formFields。添加、删除或重新序列化字段都会导致签名检查失败。
• 令牌有效期短且只能使用一次。请在上传前不久进行签名。

流程

1. 确认文件夹、文件名、标签和自定义元数据。字段必须已存在（list_custom_metadata_fields）。
2. 调用上表中的工具。
3. 使用 search_media_library、上传响应或批量命令的状态行，确认文件已上传。

说明

• 文件夹是以 / 开头的媒体库路径，而非本地路径。必要时会创建嵌套文件夹。
• 免费计划限制：图片为 25MB，视频为 100MB。每个文件最多保留 100 个版本。
• 若要保留迁移后资源的原始创建日期，请将保留的 _internal_original_created_datetime 自定义元数据键设为 ISO 8601 字符串。只有启用了原始创建日期设置的账户才会有此键；请通过 list_custom_metadata_fields 检查是否存在该键（reserved: true）。