上周帮一个做证件照自动裁剪的团队看接口文档，翻到第3页就卡住了——参数名一会儿用 img_url，一会儿是 imagePath，还有个字段叫 picBase64Str。开发小哥说：‘反正能跑通就行’。结果联调时，前端传了 base64，后端却在等 URL，来回折腾两小时。
命名别玩文字游戏
图像处理接口里，input_image 和 src_img 看似差不多，但团队里有人习惯前者，有人偏爱后者，文档一混，调用方就得猜。统一用 image_url（远程图）、image_data（二进制或 base64）、image_id（服务内 ID）这种语义清晰、带上下文的命名，比缩写炫技强得多。
状态码不是摆设
见过把所有错误都返回 500 Internal Server Error 的图像接口。用户上传一张 120MB 的 TIFF，超了限制，结果返回 500——这哪是服务器崩了，是输入不合规矩。该用 400 Bad Request 就别省；图片格式不支持，明确返回 415 Unsupported Media Type，并在文档里写清支持 jpeg、png、webp（不含 GIF 动图）。
示例要真实可粘贴
别只写 ‘请求体如下’ 然后丢一段抽象 JSON。直接给一个能复制、改改就能跑的调用示例：
{
"image_url": "https://example.com/uploads/idcard.jpg",
"options": {
"crop_mode": "face_center",
"output_format": "webp",
"quality": 85
}
}再配上对应响应：
{
"status": "success",
"result_url": "https://api.example.com/output/abc123.webp",
"size": 47289,
"width": 354,
"height": 472
}版本和变更得写明白
图像处理接口加个新参数 auto_rotate 很常见，但文档里如果只写‘新增支持自动旋转’，没人知道旧版是否兼容。得标清楚：v1.2.0 新增，非必填，默认 false；v1.1.0 及之前版本不识别该字段，忽略处理。顺手在文档顶部放个 last_updated: 2024-06-12，比写‘本文档持续更新’实在。
文档不是写完就扔一边的 PDF，它是图像处理链路里最常被打开的那扇门——门轴松了、锁舌歪了，后面的人就得反复推搡。规范不是束缚，是让每张图进来时，都知道该往哪站、怎么站、站错了谁来扶一把。