/api/v4/locations/photos/requests/{requestId}检查批量照片上传状态
返回批量照片上传请求的当前处理状态。
参数
路径
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| requestId | string | 必填 | UUID request ID returned in the `request` object by the add-photos endpoint when it queues a batch instead of uploading it inline. |
响应
200Current status of the bulk upload request, with per-photo results once available.
{ "data": { "getLocationPhotosUploadStatus": { "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a", "status": "SUCCESS", "photos": [ { "mediaId": "TWVkaWFGaWxlOjkxODI3", "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "SUCCESS", "errorMessage": null }, { "mediaId": null, "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ERROR", "errorMessage": "Image dimensions below the minimum 250x250." } ] } }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
轮询异步批量照片上传的状态。当批次足够大时,添加地点照片会在后台处理该批次,并在 request 对象中返回 requestId,而不是已处理完成的媒体。触发此行为的批次大小由服务器端配置决定,并非公开的常量,因此请通过检查是否返回了 request.requestId 来判断采用了哪种处理方式,而不是自行统计图片数量。使用该 requestId 轮询此端点,直到任务进入最终状态。
使用场景:显示上传进度条。上传大批量照片后,只要 status 为 PROCESSING,就每隔几秒轮询一次。变为 SUCCESS 或 ERROR 后,请读取 photos 数组以获取每张图片的处理结果:每个条目都包含生成的 mediaId(成功时),以及一对 status/errorMessage,以便您准确显示哪些文件被拒绝及其原因(尺寸不符、格式不受支持等),而不是将整个批次判定为失败。
状态值:PROCESSING(仍在处理中:请再次轮询)、SUCCESS(任务已完成处理)、ERROR(任务本身失败;请检查 photos[].errorMessage)。
任务的 status 仅表示处理已完成,并不表示每张图片都处理成功。状态为 SUCCESS 的任务仍可能包含被拒绝的照片,如上面的示例所示。一旦任务不再处于 PROCESSING 状态,请遍历 photos[],并读取每个条目自身的 status 和 errorMessage,以确定哪些图片已成功上传。
轮询注意事项:请在轮询之间留出等待时间:不加间隔地循环请求此端点,很快就会触发 429。请遵循 Retry-After 响应头,轮询间隔最好为几秒。未知或已过期的 requestId 无法查询到结果,因此请仅轮询最近一次上传调用返回的 ID。
curl -X GET 'https://listingsapi.com/api/v4/locations/photos/requests/<requestId>' \ -H "Authorization: API $LISTINGSAPI_KEY"