Search Response Models

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 list/search endpoints this is usually images[] plus pagination; for face search and video clipping it also includes request_id and the relevant search processing state.

Shared Photo Data Shape

BIB search and face search responses carry the shared data payload (images[] + pagination). All Photos uses the same pagination shape, but each image is metadata-enriched as ImageItemWithMeta. 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. All Photos returns ImageItemWithMeta.
`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 ImageItemWithMeta objects.
`data.pagination`	object	PaginationInfo metadata.

ImageDetailsResponse

Returned by Image Details.

{
  "responseType": "success",
  "message": "Image details",
  "data": {
    "img_url": "https://photos.9pic.ai/imgs/456/large/a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244.jpg",
    "height": 4860,
    "width": 3240,
    "image_id": "a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244",
    "thumbnail_url": "https://photos.9pic.ai/imgs/456/small/a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244.jpg",
    "original_url": null,
    "meta_info": {
      "photo_timestamp": 1700000000,
      "photographer_name": "photographer-a",
      "original_file_name": "IMG_0001.JPG",
      "source": "9Pic storage",
      "image_path": "456/photographer-a/originals/IMG_0001.JPG"
    }
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message.
`data`	object	One ImageItemWithMeta.

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 usually processing while one or more clips are being prepared. It can be terminal immediately when there are no matching video frames. Use the GET endpoint to read the latest stored state.

{
  "responseType": "success",
  "message": "Video clipping search started. Use GET /api/v1/ext/{org_id}/event/{event_id}/video-clipping/{request_id} to read the stored clip details.",
  "data": {
    "status": "processing",
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "progress_percentage": 42
  }
}

Field	Type	Description
`responseType`	string	Always `"success"` for 2xx responses.
`message`	string	Human-readable status message describing what happens next.
`data.status`	string	One of `processing`, `completed`, `no_matches`, `no_segments`, `clip_failed`, `failed`.
`data.request_id`	string	UUID for this video clipping search. Reuse with the GET endpoint and to download the resulting clips.
`data.progress_percentage`	number \| null	Approximate processing percentage while `status` is `processing`.

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.progress_percentage`	number \| null	Approximate processing percentage while `status` is `processing`.
`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://video-cdn.9pic.ai/clips/5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08/manifest/video.m3u8",
  "download_url": "https://video-cdn.9pic.ai/clips/5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08/downloads/default.mp4?filename=ddc661a7-8861-4793-9437-af42a82d12f8-source-12-event-456",
  "download_status": "ready",
  "stream_uid": "5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08",
  "thumbnail_url": "https://video-cdn.9pic.ai/clips/5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08/thumbnails/thumbnail.jpg",
  "expires_at": "2026-07-24T10:15:00Z",
  "ready_to_stream": true,
  "progress_percentage": 100,
  "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	Playback URL for the generated clip.
`download_url`	string \| null	Direct MP4 download URL when the downloadable file is ready. Prefer this for saving the file; `video_url` is for playback.
`download_status`	string \| null	Download file status when available, for example `ready` or `inprogress`.
`stream_uid`	string \| null	Provider clip identifier for support and troubleshooting.
`thumbnail_url`	string \| null	Thumbnail URL for the generated clip.
`expires_at`	string \| null	ISO-8601 timestamp requested for clip deletion.
`ready_to_stream`	boolean \| null	Whether the clip is ready to play.
`progress_percentage`	number \| null	Per-clip processing percentage.
`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[]`

Get Started

Events

Memories

Browse Photos

Search

Video

Downloads

Pipeline

Models

Overview

Shared Photo Data Shape

AllPhotosResponse

ImageDetailsResponse

BibSearchResponse

FaceSearchResponse

TimelineDaysResponse

TimelineDayItem

TimelineHourBucket

TimelineImagesResponse

VideoClippingStartResponse

VideoClippingResultResponse

VideoClipItem

VideoClipErrorItem

Used By

​Overview

​Shared Photo Data Shape

​AllPhotosResponse

​ImageDetailsResponse

​BibSearchResponse

​FaceSearchResponse

​TimelineDaysResponse

​TimelineDayItem

​TimelineHourBucket

​TimelineImagesResponse

​VideoClippingStartResponse

​VideoClippingResultResponse

​VideoClipItem

​VideoClipErrorItem

​Used By

Overview

Shared Photo Data Shape

AllPhotosResponse

ImageDetailsResponse

BibSearchResponse

FaceSearchResponse

TimelineDaysResponse

TimelineDayItem

TimelineHourBucket

TimelineImagesResponse

VideoClippingStartResponse

VideoClippingResultResponse

VideoClipItem

VideoClipErrorItem

Used By