Search Response Models - 9Pic AI Documentation

Overview

All search and photo endpoints share the unified envelope { responseType, message, data } documented in Conventions. The endpoint-specific payload always lives inside data — for photo and BIB search this is images[] plus pagination; for face search and video clipping it also includes request_id and the relevant search/job state.

Shared Photo Data Shape

Photo list, BIB search, and face search responses all carry the same data payload (images[] + pagination). Face search additionally includes request_id and confidence_percentage inside data.

{
  "images": [],
  "pagination": {
    "total": 0,
    "currentPage": 0,
    "totalPages": 0,
    "hasNextPage": false,
    "hasPreviousPage": false,
    "page_size": 32
  }
}

Field	Type	Description
`images`	array	List of ImageItem objects.
`pagination`	object	PaginationInfo metadata.

AllPhotosResponse

Returned by All Photos.

{
  "responseType": "success",
  "message": "Records for all images",
  "data": {
    "images": [],
    "pagination": {
      "total": 0,
      "currentPage": 0,
      "totalPages": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "page_size": 32
    }
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses. See Conventions.
`message`	string	Human-readable status message.
`data.images`	array	List of ImageItem objects.
`data.pagination`	object	PaginationInfo metadata.

BibSearchResponse

Returned by BIB Search.

{
  "responseType": "success",
  "message": "Records for bib number 1234",
  "data": {
    "images": [],
    "pagination": {
      "total": 0,
      "currentPage": 0,
      "totalPages": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "page_size": 32
    }
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message.
`data.images`	array	List of ImageItem objects.
`data.pagination`	object	PaginationInfo metadata.

FaceSearchResponse

Returned by Face Search (both POST and GET). The request_id and confidence_percentage are nested inside data so the envelope stays uniform across all endpoints.

{
  "responseType": "success",
  "message": "Computed face search",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "confidence_percentage": 90,
    "images": [],
    "pagination": {
      "total": 0,
      "currentPage": 0,
      "totalPages": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "page_size": 32
    }
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message.
`data.request_id`	string	Request UUID associated with the search. See request_id idempotency.
`data.confidence_percentage`	number \| null	Confidence threshold used to filter face matches. May be `null` when no threshold is configured.
`data.images`	array	List of ImageItem objects.
`data.pagination`	object	PaginationInfo metadata.

TimelineDaysResponse

Returned by GET /timeline/days (see Photo Timeline). Days are ordered ascending by date and hours[] is ordered ascending by hour.

{
  "responseType": "success",
  "message": "Timeline buckets",
  "data": {
    "days": [
      {
        "date": "2024-01-01",
        "total": 125,
        "hours": [
          { "hour": 10, "count": 98 },
          { "hour": 11, "count": 27 }
        ]
      }
    ]
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message.
`data.days`	array	List of TimelineDayItem objects.

TimelineDayItem

Each entry inside data.days[] for GET /timeline/days.

{
  "date": "2024-01-01",
  "total": 125,
  "hours": [
    { "hour": 10, "count": 98 },
    { "hour": 11, "count": 27 }
  ]
}

Field	Type	Description
`date`	string	UTC calendar date in `YYYY-MM-DD` format.
`total`	number	Total photos captured on this date.
`hours`	array	List of TimelineHourBucket entries ordered by ascending hour.

TimelineHourBucket

Each entry inside data.days[].hours[] for GET /timeline/days.

{
  "hour": 10,
  "count": 98
}

Field	Type	Description
`hour`	number	Hour of the day in UTC (`0`–`23`).
`count`	number	Number of photos captured in this hour.

TimelineImagesResponse

Returned by GET /timeline/images (see Photo Timeline). Reuses the shared photo data shape (images[] + pagination) ordered by ascending capture timestamp.

{
  "responseType": "success",
  "message": "Records for timeline window",
  "data": {
    "images": [],
    "pagination": {
      "total": 0,
      "currentPage": 0,
      "totalPages": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "page_size": 32
    }
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message.
`data.images`	array	List of ImageItem objects.
`data.pagination`	object	PaginationInfo metadata.

VideoClippingStartResponse

Returned by POST /video-clipping/search-by-selfie (see Video Clipping Search). The status is always processing on success — use the GET endpoint to wait for the terminal status.

{
  "responseType": "success",
  "message": "Video clipping search started. Poll GET /api/v1/ext/{org_id}/event/{event_id}/video-clipping/{request_id} for results.",
  "data": {
    "status": "processing",
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8"
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message describing what happens next.
`data.status`	string	Always `"processing"` when the request was accepted.
`data.request_id`	string	UUID for this video clipping search. Reuse with the GET endpoint and to download the resulting clips.

VideoClippingResultResponse

Returned by GET /video-clipping/{request_id} (see Video Clipping Search).

{
  "responseType": "success",
  "message": "Video clipping completed",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "completed",
    "videos": [],
    "error": null,
    "clip_errors": []
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message.
`data.request_id`	string	Request UUID echoed from the original `POST`.
`data.status`	string	One of `processing`, `completed`, `no_matches`, `no_segments`, `clip_failed`, `failed`.
`data.videos`	array	List of VideoClipItem objects. Empty until `status` is `completed`.
`data.error`	string \| null	Top-level error message when the job fails before any clips are generated (status `failed`).
`data.clip_errors`	array	List of VideoClipErrorItem. Populated for `clip_failed` and partially-failed `completed` results.

VideoClipItem

Each entry inside data.videos[] returned by GET /video-clipping/{request_id} when status is completed.

{
  "uuid": "5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08",
  "video_url": "https://photos.9pic.ai/vids/456/motion/selfie/ddc661a7-8861-4793-9437-af42a82d12f8/5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08.mp4",
  "source_video_key": "12",
  "start_time": "00:00:42",
  "end_time": "00:00:52"
}

Field	Type	Description
`uuid`	string	Unique identifier for the generated video clip.
`video_url`	string	Public URL where the clipped MP4 can be downloaded or streamed.
`source_video_key`	string \| null	Identifier of the configured event video source this clip was extracted from.
`start_time`	string \| null	Clip start timestamp inside the source video (`HH:MM:SS`).
`end_time`	string \| null	Clip end timestamp inside the source video (`HH:MM:SS`).

VideoClipErrorItem

Each entry inside data.clip_errors[] when the clipping service rejected one or more segments.

{
  "video_key": "34",
  "error": "Clipping service returned 500",
  "status_code": 500
}

Field	Type	Description
`video_key`	string \| null	Identifier of the event video source that failed to be clipped.
`error`	string \| null	Human-readable error message returned by the clipping service.
`status_code`	number \| null	HTTP status code returned by the clipping service, if any.

Used By

Model	Endpoint
`AllPhotosResponse`	All Photos
`BibSearchResponse`	BIB Search
`FaceSearchResponse`	Face Search (POST and GET)
`TimelineDaysResponse`	Photo Timeline — `GET /timeline/days`
`TimelineDayItem`	Inside `TimelineDaysResponse.data.days[]`
`TimelineHourBucket`	Inside `TimelineDaysResponse.data.days[].hours[]`
`TimelineImagesResponse`	Photo Timeline — `GET /timeline/images`
`VideoClippingStartResponse`	Video Clipping Search — POST
`VideoClippingResultResponse`	Video Clipping Search — GET
`VideoClipItem`	Inside `VideoClippingResultResponse.data.videos[]`
`VideoClipErrorItem`	Inside `VideoClippingResultResponse.data.clip_errors[]`

​Overview

​Shared Photo Data Shape

​AllPhotosResponse

​BibSearchResponse

​FaceSearchResponse

​TimelineDaysResponse

​TimelineDayItem

​TimelineHourBucket

​TimelineImagesResponse

​VideoClippingStartResponse

​VideoClippingResultResponse

​VideoClipItem

​VideoClipErrorItem

​Used By