Home GitHub

Upload API

Last updated

This page describes the request format, filename rule, and responses of POST /upload/{path}.

Request

Item Value
Method POST
Path /upload/{path}, where {path} is the target folder under storage/image/upload/; may contain / and is created recursively
Format multipart/form-data
File field filepath (single file)
Size limit None in the app; client_max_body_size 100M through Nginx

Supported Types

Decided by the MIME type the client sends:

MIME Stored extension
image/jpg, image/jpeg .jpg
image/png .png
image/webp .webp
image/svg+xml .svg
application/pdf .pdf

Filename

{16 random alphanumerics}_{millisecond timestamp}.{ext}, e.g. ERftP1gTS7WCTeJ8_1744080848530.jpg. The original filename is not kept.

Responses

Status Type Body
201 JSON { success: 1, filename, type, size, src }
400 Text 請至少規劃一個資料夾位置 (empty {path})
400 Text 僅支持 jpg / png / webp / svg / pdf
400 Text multer error message (e.g. "Unexpected field" when the field is not filepath)
500 Text 檔案不存在或上傳失敗 (no file in the request)

src depends on NODE_ENV: development gives http://localhost:8080/c/img/{path}/{filename}, otherwise https://{DOMAIN}/c/img/{path}/{filename}.

Example

curl -fsS -X POST \
  -F "filepath=@./photo.png" \
  http://localhost:8080/upload/products/2025 \
  || echo "upload failed"

The target folder is created before the type check, so a rejected type still leaves an empty folder behind.

中文