> ## Documentation Index
> Fetch the complete documentation index at: https://docs.9pic.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Participant App
> Build a guest gallery with FaceFind, BibTrack, Motion clips, and previews
## Overview
`9pic-client` covers a participant-facing find-my-photos app: selfie search (**9Pic FaceFind**), bib search (**9Pic BibTrack**), a photo grid, and **9Pic Motion** clips.
FaceFind, pagination, clips, and later downloads share one session. Persist the selfie `request_id` (and the bib string) in the URL. Guests see **previews** — `thumbnail_url` in the grid and watermarked `img_url` in a large view. Unlocking originals after a sale is [Media Selling](/agent-skills/9pic-media-sell).
Also install [API Skill](/agent-skills/9pic-api) for keys, identifiers, and the response envelope.
## Install
```bash theme={null}
npx skills add https://docs.9pic.ai --skill 9pic-client
```
To install every 9Pic skill, see [Agent Skills](/agent-skills).
## Session Flow
```mermaid theme={null}
sequenceDiagram
participant Guest
participant App as Partner app
participant Backend as Partner backend
participant Pic as 9Pic API
App->>Backend: Event details
Backend->>Pic: Event Details
Pic-->>Backend: Flags and name
Guest->>App: Selfie or bib
App->>Backend: Search once
Backend->>Pic: POST FaceFind or GET BibTrack
Pic-->>Backend: request_id plus preview URLs
Guest->>App: Next page or refresh
App->>Backend: Same request_id or bib
Backend->>Pic: GET cached results
Pic-->>Backend: thumbnail_url and img_url
Backend-->>App: Previews only
```
## Build the App
Call [Event Details](/api-reference/event-details) and hide selfie, bib, video, or timeline UI when the matching flag is off. A disabled feature returns `403`; retrying will not enable it.
For a selfie, follow [Face Search](/api-reference/face-search): POST once, persist `request_id` in the URL, and GET for pagination and refresh. For a bib, follow [BIB Search](/api-reference/bib-search) and keep the bib in the URL. Do not start a new search on remount or page load.
Use the search response, or [All Photos](/api-reference/all-photos), [Image Details](/api-reference/image-details), and [Photo Timeline](/api-reference/photo-timeline) for unfiltered browse. Grid cells should use thumbnail URLs from the [Image model](/api-reference/models/image). [Memories](/api-reference/memories) lists the browse, search, video, and download endpoints.
Start [Video Clipping Search](/api-reference/video-clipping-search) with the FaceFind `request_id` instead of a second selfie. Poll GET using the backoff on that page, and handle every status it documents. Keep the photo grid usable while clips process.
Grid and lightbox use `thumbnail_url` and `img_url` from the [Image model](/api-reference/models/image). If you sell unwatermarked files after your own checkout, follow [Media Selling](/agent-skills/9pic-media-sell) and [Download Originals](/api-reference/download-original-photos).
## API Pages
| When you need | Read |
| -------------------------------- | ------------------------------------------------------------- |
| Event flags | [Event Details](/api-reference/event-details) |
| Selfie search | [Face Search](/api-reference/face-search) |
| Bib search | [BIB Search](/api-reference/bib-search) |
| Browse, search, video, downloads | [Memories](/api-reference/memories) |
| Full gallery | [All Photos](/api-reference/all-photos) |
| One photo | [Image Details](/api-reference/image-details) |
| Time browse | [Photo Timeline](/api-reference/photo-timeline) |
| Thumbnail vs large | [Image model](/api-reference/models/image) |
| Next page | [Pagination](/api-reference/models/pagination) |
| Clips | [Video Clipping Search](/api-reference/video-clipping-search) |
| Cover image for an optional hero | [List Events](/api-reference/list-events) (`cover_image`) |
| Unlock originals after a sale | [Media Selling](/agent-skills/9pic-media-sell) |
## Gallery UI
The 9Pic hosted gallery uses a branded header, infinite scroll, and a lightbox. Those patterns are **optional**. Use them, mix them, or keep your existing layout. Auth, feature flags, `request_id`, and preview URLs still apply whichever UI you choose.
| Surface | 9Pic hosted gallery | Other options |
| -------- | ------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Header | Sticky bar: your logo, org name, event name, date, theme colour, optional CTA | No header; embed in your site; event title only |
| Search | Camera and file upload for selfies; one bib field | Camera only, file only, or your uploader |
| Grid | Masonry or justified thumbnails | Uniform tiles, list, timeline-only |
| Paging | Infinite scroll when `hasNextPage` is true | Numbered pages, Load more, first page only |
| Lightbox | Zoom, swipe, keyboard next/prev; prefetch neighbours; optional `?image=` + `image_id` | Photo page, drawer, grid-only |
| Clips | Status and player beside the grid | Clips-only screen, or omit Motion |
| Mobile | Large tap targets; full-screen viewer if you have a lightbox | Desktop-first, or your existing responsive layout |
| Share | Results URL with `request_id` or bib | No share surface |
**Header.** Event name and date can come from [Event Details](/api-reference/event-details). An optional banner can use `cover_image` from [List Events](/api-reference/list-events), or a file you provide. The public API does not return logo or theme colour — supply those assets yourself, or skip the header.
**Paging.** Every extra page must reuse the same search / `request_id`. Never POST a new selfie to load more. `hasNextPage` is on the [Pagination model](/api-reference/models/pagination).
**Lightbox.** Grid cells use `thumbnail_url`; the viewer uses watermarked `img_url` from the [Image model](/api-reference/models/image). Paid unwatermarked files are [Media Selling](/agent-skills/9pic-media-sell).
[Branding & Theme](/dashboard-guide/settings/branding) and [Photo Branding](/dashboard-guide/photos/branding) show how the hosted 9Pic gallery looks. They are a visual reference only — a custom app supplies its own logo and colour, or skips branding.
## Integration Notes
* The browser never sends `X-API-Key`. See [API Skill](/agent-skills/9pic-api).
* A fresh FaceFind POST is a new search. Reuse `request_id` for pagination, clips, and downloads.
* Read Event Details before calling FaceFind, BibTrack, Motion, or timeline.
* Import, process, and go-live are organiser pipeline endpoints — see [Memories](/api-reference/memories).
* **Flow**, **Certify**, and **Buzz** have no public `/ext/` API.
## Related
Auth, envelope, identifiers, and errors.
How browse, search, video, and downloads group.
POST once, GET many, persist `request_id`.
Your checkout, then originals.