GET/api/v4/locations/photos/requests/{requestId}

检查批量照片上传状态

返回批量照片上传请求的当前处理状态。

需要 API 密钥。请求头格式和密钥轮换请参阅身份验证。

参数

路径

名称类型必填描述
requestIdstring必填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.
Response
{  "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。

Request
curl -X GET 'https://listingsapi.com/api/v4/locations/photos/requests/<requestId>' \  -H "Authorization: API $LISTINGSAPI_KEY"