JCJC 图片处理工具 API v4 接口文档

基础路径 (Base URL): https://www.cuobiezi.net/api/v4/image-tools

🛡️ 接口鉴权 (Authentication)

所有接口均需在 HTTP Header 中携带 Bearer Token 进行请求鉴权。Token 可在字根秀秀后台申请。

• 鉴权方式: Authorization: Bearer <your_api_key>
• 申请地址: https://www.cuobiezi.net/user/api_keys/list

📝 请求说明

所有接口均为 POST 请求，使用 multipart/form-data 格式上传文件和传递参数。
除 /metadata 返回 JSON 格式的图片元数据外，其他接口均直接返回处理后的二进制图片流。

1. 图片加壳 (Mockup)

路径: /mockup
用途: 为图片添加背景、阴影、圆角和水印，生成精美的 Mockup 效果图。

参数:

• file (必须): 上传的图片文件
• background_color: 背景颜色 (如 #FF6B6B)
• watermark_text: 水印文字
• watermark_font_size: 水印字体大小
• watermark_color: 水印颜色 (如 #000)
• watermark_margin_left: 水印左边距
• watermark_margin_bottom: 水印下边距
• watermark_bg_enabled: 是否开启水印背景
• watermark_bg_shape: 水印背景形状
• watermark_bg_color: 水印背景颜色
• watermark_render_method: 水印渲染方式
• watermark_bold: 是否粗体
• watermark_bg_padding_h: 水印背景水平内边距
• watermark_bg_padding_v: 水印背景垂直内边距
• watermark_bg_radius: 水印背景圆角
• shadow_offset_x: 阴影水平偏移
• shadow_offset_y: 阴影垂直偏移
• shadow_blur: 阴影模糊度
• shadow_color: 阴影颜色
• shadow_enabled: 是否开启阴影 (true 或 false)
• shadow_opacity: 阴影透明度
• corner_radius: 图片圆角
• scale_factor: 图片缩放比例

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/mockup \
  -F "file=@input.png" \
  -F "background_color=#FF6B6B" \
  -F "corner_radius=30" \
  -F "shadow_enabled=true" \
  -o output_mockup.png

2. 图片缩放 (Resize)

路径: /resize
用途: 根据指定的宽度和高度缩放图片（保持纵横比）。

参数:

• file (必须): 上传的图片文件
• width: 目标宽度 (像素)
• height: 目标高度 (像素)

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/resize \
  -F "file=@input.png" \
  -F "width=800" \
  -F "height=600" \
  -o output_resized.png

3. 图片放大 (Enlarge)

路径: /enlarge
用途: 无损放大图片分辨率以优化细节。

参数:

• file (必须): 上传的图片文件
• width: 目标宽度
• height: 目标高度

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/enlarge \
  -F "file=@input.png" \
  -F "width=2000" \
  -F "height=2000" \
  -o output_enlarged.png

4. 图片裁剪 (Crop)

路径: /crop
用途: 将图片裁剪到指定的尺寸，支持智能裁剪或按引力方向裁剪。

参数:

• file (必须): 上传的图片文件
• width: 裁剪宽度
• height: 裁剪高度
• gravity (可选): 裁剪重心，如 centre, north, south, east, west
• smart (可选): 是否启用智能裁剪 (true 或 false)

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/crop \
  -F "file=@input.png" \
  -F "width=500" \
  -F "height=500" \
  -F "gravity=centre" \
  -o output_cropped.png

5. 图片旋转 (Rotate)

路径: /rotate
用途: 按指定角度旋转图片。

参数:

• file (必须): 上传的图片文件
• angle: 旋转角度，例如 90, 180, 270 等

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/rotate \
  -F "file=@input.png" \
  -F "angle=90" \
  -o output_rotated.png

6. 垂直翻转 (Flip)

路径: /flip
用途: 对图片进行上下镜像翻转。

参数:

• file (必须): 上传的图片文件

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/flip \
  -F "file=@input.png" \
  -o output_flipped.png

7. 水平翻转 (Flop)

路径: /flop
用途: 对图片进行左右镜像翻转。

参数:

• file (必须): 上传的图片文件

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/flop \
  -F "file=@input.png" \
  -o output_flopped.png

8. 缩放系数 (Zoom)

路径: /zoom
用途: 按指定的倍数快速放大或缩小图片。

参数:

• file (必须): 上传的图片文件
• factor: 缩放系数（如 2 表示放大两倍，0.5 表示缩小一半）

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/zoom \
  -F "file=@input.png" \
  -F "factor=2" \
  -o output_zoomed.png

9. 生成缩略图 (Thumbnail)

路径: /thumbnail
用途: 根据提供的宽高生成图片缩略图。

参数:

• file (必须): 上传的图片文件
• width: 缩略图宽度
• height (可选): 缩略图高度

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/thumbnail \
  -F "file=@input.png" \
  -F "width=200" \
  -o output_thumbnail.png

10. 提取区域 (Extract)

路径: /extract
用途: 基于坐标精确提取图片中的某个矩形区域。

参数:

• file (必须): 上传的图片文件
• top: 顶端 Y 坐标
• left: 左侧 X 坐标
• width: 提取的宽度
• height: 提取的高度

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/extract \
  -F "file=@input.png" \
  -F "top=100" \
  -F "left=100" \
  -F "width=400" \
  -F "height=300" \
  -o output_extracted.png

11. 添加水印 (Watermark)

路径: /watermark
用途: 在图片上添加自定义文字水印。

参数:

• file (必须): 上传的图片文件
• text: 水印文字
• opacity: 透明度 (如 0.6)
• margin: 边距
• font: 字体配置 (如 sans bold 24)
• position: 位置配置

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/watermark \
  -F "file=@input.png" \
  -F "text=版权所有" \
  -F "opacity=0.6" \
  -F "margin=20" \
  -o output_watermarked.png

12. 模糊效果 (Blur)

路径: /blur
用途: 给图片应用高斯模糊效果。

参数:

• file (必须): 上传的图片文件
• sigma: 模糊强度（如 10.0）

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/blur \
  -F "file=@input.png" \
  -F "sigma=10.0" \
  -o output_blurred.png

13. 色彩空间转换 (Colorspace)

路径: /colorspace
用途: 转换图片的色彩空间（例如转为黑白或灰度）。

参数:

• file (必须): 上传的图片文件
• space: 色彩模式，如 bw (黑白), greyscale

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/colorspace \
  -F "file=@input.png" \
  -F "space=bw" \
  -o output_bw.png

14. 格式转换 (Convert)

路径: /convert
用途: 将图片转换为其他格式，并可以调整压缩质量。

参数:

• file (必须): 上传的图片文件
• format: 目标格式，支持 png, jpeg, webp, avif
• quality: 输出质量（1-100）

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/convert \
  -F "file=@input.png" \
  -F "format=webp" \
  -F "quality=80" \
  -o output.webp

15. 读取元数据 (Metadata)

路径: /metadata
用途: 获取图片的 EXIF 及其他元数据信息，返回格式为 JSON。

参数:

• file (必须): 上传的图片文件

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/metadata \
  -F "file=@input.png"

16. 裁剪边缘 (Trim)

路径: /trim
用途: 自动去除图片边缘的透明或纯色区域。

参数:

• file (必须): 上传的图片文件
• threshold: 裁剪容差阈值 (如 10)

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/trim \
  -F "file=@input.png" \
  -F "threshold=10" \
  -o output_trimmed.png

17. 批量综合处理 (Process)

路径: /process
用途: 提供统一入口，允许将多个图片处理参数一并提交，由系统按照内部处理链自动对图片进行各种组合操作（如裁剪+旋转+转换格式）。

参数:

• file (必须): 上传的图片文件
• * (动态参数): 任何上述可用的操作参数（如 format, width, rotate, blur 等组合）

Curl 示例:

curl -H "Authorization: Bearer <your_api_key>" \
  -X POST https://www.cuobiezi.net/api/v4/image-tools/process \
  -F "file=@input.png" \
  -F "width=600" \
  -F "rotate=90" \
  -F "blur=2.0" \
  -F "format=jpeg" \
  -F "quality=90" \
  -o output_processed.jpg