SnapOtter/apps/docs/zh-CN/tools/image/edit-metadata.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash

description	i18n_source_hash	i18n_provenance	i18n_output_hash
编辑图片中的 EXIF、IPTC、GPS 和 XMP 元数据字段，无需重新编码像素。	a37746db11c3	human	7b3853980f3b

编辑元数据

编辑图片的元数据字段，包括 EXIF、IPTC、GPS 坐标、日期和关键词。底层使用 ExifTool，因此元数据是就地写入的，无需重新编码像素，从而完整保留图片质量。

API 端点

编辑元数据

POST /api/v1/tools/image/edit-metadata

将元数据字段写入图片并返回修改后的文件。

检查元数据

POST /api/v1/tools/image/edit-metadata/inspect

通过 ExifTool 以 JSON 形式返回图片的完整元数据。不会修改图片。

参数（编辑）

参数	类型	必填	默认值	说明
title	string	否	-	图片标题（XMP/EXIF）
author	string	否	-	作者姓名
artist	string	否	-	艺术家姓名（EXIF Artist 标签）
copyright	string	否	-	版权声明
imageDescription	string	否	-	图片描述（EXIF）
software	string	否	-	软件标签
dateTime	string	否	-	EXIF DateTime 值
dateTimeOriginal	string	否	-	EXIF DateTimeOriginal 值
setAllDates	string	否	-	一次性设置所有日期字段
dateShift	string	否	-	按偏移量平移所有日期（格式：+HH:MM 或 -HH:MM）
clearGps	boolean	否	false	移除所有 GPS 数据
gpsLatitude	number	否	-	设置 GPS 纬度（-90 至 90）
gpsLongitude	number	否	-	设置 GPS 经度（-180 至 180）
gpsAltitude	number	否	-	设置 GPS 海拔，单位米
keywords	string[]	否	-	要添加或设置的关键词/标签
keywordsMode	string	否	"add"	关键词处理方式：add（追加）或 set（替换）
fieldsToRemove	string[]	否	[]	要移除的特定元数据字段名列表
iptcTitle	string	否	-	IPTC 对象名称
iptcHeadline	string	否	-	IPTC 标题
iptcCity	string	否	-	IPTC 城市
iptcState	string	否	-	IPTC 省/州
iptcCountry	string	否	-	IPTC 国家

请求示例

设置作者和版权：

curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"author": "Jane Smith", "copyright": "2024 Jane Smith"}'

设置 GPS 坐标：

curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"gpsLatitude": 48.8566, "gpsLongitude": 2.3522, "gpsAltitude": 35}'

移除 GPS 并添加关键词：

curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"clearGps": true, "keywords": ["landscape", "sunset"], "keywordsMode": "add"}'

检查元数据：

curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata/inspect \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg"

响应示例（编辑）

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
  "originalSize": 2450000,
  "processedSize": 2452000
}

注意事项

• 此工具需要在服务器上安装 ExifTool。Docker 镜像中已包含它。
• 元数据是就地写入的，因此不会发生像素重新编码。文件大小的变化极小（仅为元数据字节）。
• dateShift 参数按指定偏移量平移所有日期字段，适用于修正时区错误（例如 +02:00 或 -05:30）。
• 如果未请求任何更改（所有参数都省略或为空），则原始文件将原样返回。
• 支持的格式：JPEG、PNG、WebP、AVIF、TIFF、GIF、HEIC/HEIF。
• 对于无法在浏览器中预览的格式（HEIF、TIFF），响应会包含一个 previewUrl 字段，附带 WebP 预览。