Spring Boot调用ThumbSnap API传图报400错误（无API密钥）排查

我在Spring Boot项目里集成ThumbSnap的图片上传API，已经按文档定义了响应DTO、写了Service上传逻辑和Controller接口，但用Postman调用时返回400错误，提示“No API key specified. Upload stopped”。我确认过API密钥是对的，想问问核心代码有没有问题，以及怎么正确发请求解决这个问题。

ThumbSnap核心上传API说明 #

ThumbSnap提供免费API用于程序化上传、托管图片和视频，上传核心要求：

• 必填字段：
  • media：图片/视频二进制数据，必须以multipart/form-data格式的HTTP POST发送
  • key：ThumbSnap提供的API密钥
• 上传成功后返回JSON格式响应，包含url字段为图片的完整页面URL，示例响应：

{
  "data": {
    "id": "soLHmGdX",
    "url": "https://thumbsnap.com/soLHmGdX",
    "media": "https://thumbsnap.com/i/soLHmGdX.png",
    "thumb": "https://thumbsnap.com/t/soLHmGdX.jpg",
    "width": 224,
    "height": 224
  },
  "success": true,
  "status": 200
}

我的响应DTO代码 #

public record ThumbSnapResponseDTO(
        @JsonProperty(value = "data")
        DataDTO data,
        boolean success,
        int status
) {
        public record DataDTO(
                String id,
                String url,
                String media,
                String thumb,
                int width,
                int height
        ) {}
}

核心上传代码 #

MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
body.add("key", THUMB_SNAP_API_KEY);
body.add("media", new ByteArrayResource(imageData) {
    @Override
    public String getFilename() {
        return filename;
    }
});

HttpEntity<MultiValueMap<String, Object>> requestEntity = new HttpEntity<>(body, headers);
restTemplate.getMessageConverters().add(new MultiPartMessageConverter(objectMapper));

ResponseEntity<ThumbSnapResponseDTO> response =
        restTemplate.exchange(
                THUMB_SNAP_BASE_URL,
                HttpMethod.POST,
                requestEntity,
                ThumbSnapResponseDTO.class
        );

错误响应 #

{
    "code": "EXECUTION",
    "message": "org.springframework.web.client.HttpClientErrorException$BadRequest: 400 Bad Request: \"No API key specified. Upload stopped\""
}

问题分析与解决方法 #

1. 核心代码的潜在问题

• 转换器添加时机错误：在创建请求实体后才给RestTemplate添加MultiPartMessageConverter，此时RestTemplate已初始化完成，新转换器不会生效，导致multipart请求解析异常。
• Headers可能干扰请求格式：如果手动设置了headers，可能覆盖Spring自动生成的multipart/form-data及边界值，导致服务端无法正确解析表单字段。
• 文件名缺失风险：若filename为空，可能导致服务端解析整个multipart请求失败，连带key字段未被识别。

2. 修正后的核心代码

// 初始化RestTemplate时配置好转换器（建议放到配置类中统一管理）
RestTemplate restTemplate = new RestTemplate();
MappingJackson2HttpMessageConverter jacksonConverter = new MappingJackson2HttpMessageConverter();
jacksonConverter.setObjectMapper(objectMapper);
restTemplate.getMessageConverters().add(new FormHttpMessageConverter());
restTemplate.getMessageConverters().add(jacksonConverter);

// 构建请求体
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
body.add("key", THUMB_SNAP_API_KEY);
// 确保文件名不为空且带合法后缀
body.add("media", new ByteArrayResource(imageData) {
    @Override
    public String getFilename() {
        return filename != null ? filename : "uploaded-image.png";
    }
});

// 不手动设置headers，让Spring自动生成multipart格式的请求头
HttpEntity<MultiValueMap<String, Object>> requestEntity = new HttpEntity<>(body);

ResponseEntity<ThumbSnapResponseDTO> response =
        restTemplate.exchange(
                THUMB_SNAP_BASE_URL,
                HttpMethod.POST,
                requestEntity,
                ThumbSnapResponseDTO.class
        );

3. Postman请求的正确发送方式

• 请求方法：POST
• 请求URL：你的Controller接口地址
• 请求体：选择form-data格式，添加对应字段：
  • 图片字段：字段名需和Controller接收参数名一致，选择本地图片文件上传
  • 其他参数：若Controller需要额外参数，按定义添加即可
• 注意：不要手动设置Content-Type，Postman会自动生成包含边界值的multipart/form-data头

额外检查点

• 打印日志验证THUMB_SNAP_API_KEY是否正确注入，无空值或拼写错误
• 确认THUMB_SNAP_BASE_URL是ThumbSnap官方上传API地址（通常为https://thumbsnap.com/api/upload）
• 检查服务端网络环境，确保能正常访问ThumbSnap的API域名

内容的提问来源于stack exchange，提问作者Crazy Coder