Công cụ ảnh địa phương dành cho nhà phát triển và trợ lý

Hình mờ hàng loạt miễn phí, nhãn tên tệp và tem ngày. Khám phá các khả năng, sau đó xử lý các ảnh được chọn rõ ràng trên thiết bị.

Đọc dưới dạng Markdown · OpenAPI 3.1 · Lược đồ công thức

Chọn một bề mặt thực hiện

Khám phá API là công khai, miễn phí, chỉ đọc và không yêu cầu khóa API. Nó mô tả các công cụ và cài đặt; nó không bao giờ chấp nhận hình ảnh. Không có POST/hình mờ, dịch vụ xử lý đám mây hoặc điểm cuối MCP được lưu trữ.

Sử dụng trình duyệt SDK cho các Tệp được chọn rõ ràng trên nguồn gốc này. Để có trợ lý có quyền truy cập hệ thống tệp cục bộ, hãy kết nối rõ ràng máy chủ stdio MCP của kho lưu trữ và ủy quyền cho một thư mục gốc. Mô hình tìm thấy tài liệu này sẽ không có quyền truy cập vào thiết bị hoặc các tệp của thiết bị.

bề mặt	Mục đích
NHẬN JSON / Đánh dấu	Khám phá các khả năng, công thức nấu ăn, các ràng buộc và chữ ký công cụ cục bộ.
Trình duyệt ESM SDK	Giải mã và hiển thị tệp cục bộ; yêu cầu Canvas, DOM, createImageBitmap và File/Blob. Không phải Node hoặc API xử lý HTTP từ xa.
CLI / stdio cục bộ MCP	Tự động hóa cục bộ được kết nối rõ ràng bằng cách sử dụng Google Chrome đã cài đặt và các phần phụ thuộc của kho lưu trữ.

Tài nguyên công cộng

GET và HEAD trả về tài nguyên tĩnh. Không có xác thực, nội dung yêu cầu, tham số truy vấn hoặc dữ liệu người dùng. Đường dẫn tài nguyên không xác định trả về 404. Coi phiên bản 1 là phiên bản hợp đồng; đánh dấu các đường dẫn chuẩn thay vì các đoạn xây dựng được băm. Quyền truy cập trình duyệt nhiều nguồn gốc không được hứa hẹn; sử dụng hàng nhập khẩu SDK có cùng nguồn gốc.

curl https://watermark.noxxxx.com/api/v1/capabilities.json
curl https://watermark.noxxxx.com/api/v1/recipes/filename.json

Trình duyệt SDK

Nhập /sdk/watermark.js trên nguồn gốc của trang này. Đây là URL mục nhập ESM ổn định; các phần thực hiện có thể thay đổi. Ví dụ sau yêu cầu nhập nhiều tệp và chạy sau khi người dùng chọn tệp cục bộ. Nó tạo ra một ZIP gồm các bản sao thành công; người gọi phải kiểm tra failures và cancelled thay vì coi việc xuất một phần là hoàn tất.

import { createRecipe, validateRecipe, inspectImage, processBatch, packageResults }
  from '/sdk/watermark.js';

// Run on this site's origin in a modern browser, after explicit file selection.
const files = [...document.querySelector('input[type="file"]').files];
const recipe = createRecipe('filename'); // watermark | filename | date | frame
const errors = validateRecipe(recipe);
if (errors.length) throw new Error(errors.join('; '));
const records = [];
try {
  for (const file of files) records.push(await inspectImage(file));
  const result = await processBatch(records, recipe);
  if (result.failures.length || result.cancelled) {
    console.warn('Check partial results before downloading', result);
  }
  if (result.entries.length) {
    const zip = await packageResults(result.entries);
    const url = URL.createObjectURL(zip);
    const link = document.createElement('a');
    link.href = url; link.download = 'labeled-photos.zip'; link.click();
    setTimeout(() => URL.revokeObjectURL(url), 30000);
  }
} finally {
  records.forEach(record => URL.revokeObjectURL(record.thumbnail));
}

chức năng	Đầu vào → kết quả
createRecipe(mode)	watermark \| filename \| date \| frame → công thức v1 độc lập.
validateRecipe(recipe)	Công thức → lỗi chuỗi[]; trống nghĩa là cấu hình hợp lệ. Xác thực ngữ nghĩa cũng kiểm tra các ID duy nhất và giới hạn cắt.
inspectImage(file)	File → Promise<Record> với id, tên, tệp, chiều rộng, chiều cao, URL đối tượng hình thu nhỏ, ghi đè, siêu dữ liệu, cảnh báo siêu dữ liệu. Thu hồi hình thu nhỏ khi hoàn tất.`{id,name,file,width,height,thumbnail,overrides,metadata,metadataWarning}`
renderImage(record, recipe, options?)	→ Promise<{blob, geometry}>; preview:true trả về {canvas, geometry}. tùy chọn: nội dung:Map<assetId,ImageBitmap\|Canvas>, chỉ mục:số, maxDimension:số, canvas:Canvas. missingMetadataText?:string.`{blob,geometry} \| {canvas,geometry}`
processBatch(records, recipe, options?)	→ Promise<{entries,failures,cancelled}>. Mục nhập: {name,blob,width,height,sourceId}; lỗi: {id,name,longEdge,message}. tùy chọn: tài sản, tín hiệu:AbortSignal, onProgress({done,total,failed}), onResult(entry). missingMetadataText?:string.`{entries:[{name,blob,width,height,sourceId}],failures:[{id,name,longEdge,message}],cancelled}`
packageResults(entries)	→ Promise<Blob> ZIP; từ chối khi sản lượng kết hợp vượt quá 450 MiB.
decodeImage(blob)	→ Promise<ImageBitmap>; close() khi hoàn tất. HEIC sử dụng hình ảnh được giải mã đầu tiên.
parseLabelCsv(text)	filename,text CSV → Map<chuỗi,chuỗi>; khớp tên chính xác, từ chối tên trùng lặp. Hãy tự cài đặt record.label trước khi xử lý.
imageRecipe(recipe, record)	Hợp nhất record.overrides.image và record.overrides.layers[id] mà không làm thay đổi công thức được chia sẻ.
renderStudioImage / cleanLogo	Người trợ giúp Canvas cấp thấp; xem gói kho lưu trữ/watermark-core/src/studio.js để biết chữ ký. Ưu tiên renderImage cho đầu ra được mã hóa.

Quy tắc và lỗi công thức

Tải xuống công thức nấu ăn đầy đủ từ /api/v1/recipes/watermark.json, filename.json, date.json hoặc frame.json. Xác thực JSON Schema trước, sau đó là validateRecipe để kiểm tra ngữ nghĩa. ID lớp phải là duy nhất. Cắt x + chiều rộng và y + chiều cao phải nằm trong ảnh. Kích thước, lề, đường viền và chân trang sử dụng tỷ lệ phần trăm của cạnh ngắn của hình ảnh được cắt và xoay. Đầu ra longEdge:0 giữ nguyên kích thước; thay đổi kích thước không bao giờ nâng cấp. image.crop.aspectRatio tùy chọn là tỷ lệ rộng/cao của nội dung sau khi xoay. Mỗi ảnh được cắt giữa vùng chọn chuẩn hóa riêng, kể cả khi kích thước khác nhau. Viền và chân trang được thêm sau. Chỉnh phần trăm thủ công sẽ xóa quy tắc tỷ lệ.

Biến văn bản: {filename} không bao gồm phần mở rộng; {fullname} bao gồm nó; {index} sử dụng sequence.start và phần đệm; {label} sử dụng record.label. Các biến số của máy ảnh là {camera}, {lens}, {aperture}, {iso}, {shutter}, {focal}. CSV không tự động điền các bản ghi SDK.

Ngày đặt trước sử dụng DateTimeOriginal hoặc CreateDate của mỗi hình ảnh. Không có ngày sửa đổi tập tin được thay thế. Thiếu ngày mặc định có nhãn ngày trống; missing:error không thành công hình ảnh đó, missing:custom sử dụng date.custom nếu có thể phân tích cú pháp. source:custom sử dụng ngày được cung cấp trực tiếp. Ngày tùy chỉnh không phải là dấu thời gian được chứng nhận. Theo chính sách này, ngày không hợp lệ có thể mang lại nhãn trống hoặc lỗi.

Công thức chứa các cài đặt chứ không phải byte logo hoặc phông chữ tùy chỉnh. Cung cấp logo thông qua options.assets được khóa bởi layer.assetId và đóng bitmap logo đã giải mã sau khi sử dụng. Phông chữ tùy chỉnh phải được tải vào document.fonts thuộc họ LocalFont của chúng. Thiếu tài nguyên thất bại một cách rõ ràng.

SDK đưa ra các công thức nấu ăn không hợp lệ trước khi thực hiện hàng loạt. Lỗi giải mã, kết xuất, siêu dữ liệu hoặc mã hóa trên mỗi hình ảnh xuất hiện trong failures, trong khi entries thành công vẫn có sẵn. Các lỗi hiện chứa các tin nhắn tiếng Trung mà con người có thể đọc được; người tiêu dùng không nên phân nhánh trên văn bản của họ. Việc hủy bỏ được kiểm tra giữa các đầu ra; kết xuất hiện tại không bị gián đoạn. Với onResult, entries được gửi tới lệnh gọi lại và không được giữ lại trong mảng entries được trả về.

Giới hạn và quyền riêng tư

Không có hạn ngạch số lượng ảnh phải trả tiền, tài khoản, khóa API, đăng ký hoặc nhãn hiệu trang web được thêm vào. Mỗi đầu vào được giới hạn ở 150 MiB và 120 triệu pixel; Đầu ra ZIP được giới hạn ở 450 MiB. Tối đa 30 lớp, 6 kích thước đầu ra bổ sung, cạnh dài lên tới 32768. Giới hạn trình duyệt Canvas, bộ nhớ, bộ giải mã và hệ thống tệp có thể thấp hơn; chia lô lớn.

Đầu ra là JPEG, PNG hoặc WebP. JPEG và WebP bị mất dữ liệu được mã hóa lại. Chế độ siêu dữ liệu mặc định là strip. Chế độ safe và all yêu cầu đầu ra JPEG. Chế độ safe không bao gồm GPS; chế độ all có thể giữ lại siêu dữ liệu vị trí. Cấu hình ICC, HDR và chữ ký không được bảo tồn. Các tập tin gốc không bao giờ bị thay đổi.

Chỉ tài nguyên chương trình được lưu vào bộ nhớ đệm tùy chọn để sử dụng ngoại tuyến trong /studio/.. Các trang công khai mới cần có kết nối mạng để tải ban đầu. Hình ảnh và tên tệp của người dùng không được gửi tới API công khai hoặc được lưu trữ trong các cài đặt trước. Chỉ lưu/chia sẻ các công thức nấu ăn không chứa văn bản riêng tư.

MCP cục bộ

Khả năng này được cung cấp bởi kho lưu trữ chứ không phải điểm cuối internet. Điều kiện tiên quyết: Node.js, pnpm cài đặt trong kho lưu trữ và cài đặt Google Chrome. Chạy máy chủ từ kho lưu trữ, với một thư mục được phép rõ ràng. Không suy ra đường dẫn hệ thống tệp riêng tư từ kết quả tìm kiếm trên web.

node scripts/watermark-mcp.mjs --root /absolute/authorized/photo-folder

Công cụ	Đầu vào và kết quả
validate_recipe	{recipe} → {errors:string[]}. Không đọc hình ảnh.
inspect_images	{files:string[]} → {images:[{id,name,width,height,metadata,metadataWarning}],failures:[{id,name,index,stage,message}]}.
preview_watermark	{files,recipe,output?,logos?} → {files:[{path,width,height}],failures,cancelled}. Chỉ ghi hình ảnh đầu tiên, cạnh dài nhất 1400.
batch_watermark	{files,recipe,output?,logos?} → {files:[{path,width,height}],failures,cancelled}. Ghi từng hình ảnh riêng lẻ, không phải ZIP.

Đường dẫn đầu vào trong files được giải quyết bên trong --root. Bản đồ logos liên kết ID nội dung với các đường dẫn trong cùng một gốc. Mặc định output là watermark-output bên trong thư mục gốc; đường dẫn tuyệt đối cũng phải nằm trong thư mục gốc này. Các lối thoát liên kết tượng trưng bị từ chối. Các tệp hiện có được bảo tồn bằng cách chọn tên tệp đầu ra mới. Lược đồ xem trước và xử lý hàng loạt yêu cầu recipe; inspect_images chỉ nhận files. Ảnh lỗi nằm trong failures, ảnh hợp lệ vẫn tiếp tục. index bắt đầu từ 0 trong mảng files gốc; stage là inspect hoặc render. Xem trước chỉ xử lý files[0], không thay bằng ảnh khác. Yêu cầu không hợp lệ trả về isError kèm theo tin nhắn văn bản; lỗi xử lý riêng lẻ vẫn còn ở failures. Cuộc gọi là yêu cầu/phản hồi và không có công cụ hủy bỏ.

MCP trả về JSON được tuần tự hóa bên trong content[0].text, không phải structuredContent. Kiểm tra và xác thực ở chế độ chỉ đọc; xem trước và viết hàng loạt bản sao. Không có công cụ tải ảnh lên. Máy khách phải cấu hình rõ ràng lệnh stdio cục bộ này trước khi sử dụng các công cụ.