9Pic Integration

​

Overview

• Any API call: create and send an API key, keep it on your backend, and read the shared envelope, pagination, and errors.
• Participant app: a find-my-photos app with selfie search (9Pic FaceFind), bib search (9Pic BibTrack), a photo grid, timeline, and 9Pic Motion clips. Guests see previews.
• Selling originals: you take payment in your own checkout, then your backend unlocks original photos.
• Review: once your app is built, the agent checks it against these practices and writes a report of Must have and Good to have fixes.

​

Install

npx skills add https://docs.9pic.ai

​

Call Path

​

Pick the Job

​

Keep the Key Off the Frontend

• Read it only in server code, from a server-only environment variable such as NINEPIC_API_KEY.
• Never give it a public prefix that bundlers ship to the browser: VITE_, NEXT_PUBLIC_, REACT_APP_, EXPO_PUBLIC_, NUXT_PUBLIC_, PUBLIC_, GATSBY_. Never import it into a client component.
• Mobile and desktop apps call your backend too. Don’t put the key in app config, Info.plist, BuildConfig, or a bundled .env.
• Expose specific backend routes (event, search, page, download after a sale). Don’t build a catch-all proxy that forwards any path to api.9pic.ai with the key attached; that gives anyone the key’s full access.
• Never return the key, echo request headers, or log it. Keep .env files out of version control.

​

API Pages

​

Participant App

​

Save the Search ID

​

Backend

• Dropped connection: read the search back with the saved ID. If it completed, you get the stored result. A 404 means it was never recorded: POST again with the same ID.
• Failed or empty search: a search ID keeps its first stored result. To try again, start a fresh search with a new ID.
• New selfie: a new selfie is a new search, so give it a new ID. Never reuse an ID across events.

​

Frontend

• Put the search ID in the URL after the first search, for example /events/456/results/ddc661a7-8861-4793-9437-af42a82d12f8. On load, if the URL has an ID, ask your backend for that search; never upload the selfie again.
• Page with the same ID. Infinite scroll, Load more and numbered pages all read the same search until hasNextPage is false.
• Upload once. Refreshes, remounts, back navigation and new pages must not trigger a new upload.
• Choose shareable or private with the organiser. Shareable is the default, like the 9Pic gallery: anyone with the link sees those previews, and search IDs are random UUIDs. Private: your backend serves a saved search only to the user or session that created it. Without logins, use an anonymous httpOnly session cookie as the user.

​

Gallery Behaviour

​

State lives in the URL

• The URL holds the active view: the search type and its value (selfie search ID or bib), plus the timeline day and time window. A refresh or a shared link reopens the same view and never starts a new search.
• Starting a search adds a history entry, so Back returns to the event page. A “Back” or “Clear search” control returns to the plain event URL.
• The open photo, scroll position and loaded pages do not need to survive a refresh. A photo param such as ?image=<image_id> is optional.

​

Event first

• Read Event Details once per page load. Show only the searches whose flags are on; clips need both video_search and video_selfie_search. If every search flag is off, show no search box, just the gallery.
• If event_enabled is false, show a “Photos coming soon” message instead of search and grid. The search endpoints do not block on this flag, so the app must.
• Some settings the hosted gallery follows are not available with an API key: whether downloads are allowed, whether all photos can be browsed, the photo count, the selfie capture mode, the organiser’s bib format, albums, password and sale window. Agree them with the organiser; do not guess them from other fields. (Event Settings returns some of them, but only to an organiser admin signed in with OAuth.)
• name_search reports an organiser setting. The public API has no name-search endpoint, so do not build one.

​

Selfie search

1. Consent first. Before the camera or file picker, show a short step: what makes a good selfie (one person, face to camera, good light, no sunglasses or face covering), how the selfie is used (only to find this participant’s photos, per your privacy policy), and an “I understand” button. If a small selfie thumbnail stays on the device (step 4), say so instead of promising that nothing is kept.
2. Capture. Offer camera, file upload, or both, as the organiser prefers (the hosted gallery defaults to both). Accept JPEG and PNG only (reject HEIC and others with a clear message), one file. Respect EXIF orientation and compress in the browser (JPEG quality about 0.6, downscaling if needed) so the upload is at most 1.5 MB. Phone photos are often larger than that, so compress first and reject only a file that is still too large.
3. Search once. Create the search first, then upload to it, as the hosted gallery does: the browser asks your backend for a new search, the backend creates and saves the search ID and returns it, and the browser uploads the selfie for that ID. If the upload fails on a network error, or your backend answers 502, 503, or 504 (for example a serverless timeout), try again for the same ID, up to 3 attempts in total, 1 s apart; never retry a 429. On serverless hosts, give the selfie route a timeout long enough for Face Search. Because every attempt carries the same ID, a retry can’t run a second search. For an ID it has already sent to 9Pic, the backend reads the result back first (see Save the Search ID).
4. Show results. On success put the ID in the URL and show “Found N photos” with the participant’s own selfie thumbnail (kept on the device only) and a Search someone else action.
5. Remember one search per event. Remember the last search ID per event that found photos (on the device, or with the signed-in user). Clicking the selfie button again on that event reopens it instead of asking for a new upload. Search someone else forgets that search and its thumbnail and returns to the event page; the next selfie gets a new ID. A failed upload is not remembered. When a search finds nothing, show the empty state with a Try another photo action that starts a new search.

​

BIB search

• While typing, accept letters, digits, -, / and spaces only. Before searching, trim and uppercase.
• If the organiser gives a bib format (a pattern, a numeric length range, or a number range), validate against it. Otherwise allow search for digits only (any length), digits followed by one letter, or at least 3 characters of letters, digits and -.
• Put the bib in the URL and URL-encode it in the backend path.
• Empty result text: “No photos found for bib number {bib}. Please try another bib number.” An unknown bib returns an empty list, not an error. A 404 means the event has no photo setup: show “Photos coming soon”, not the empty-bib text.

​

Grid and paging

• Every list (all photos, selfie, bib, timeline) uses pages of 32. Load the next page automatically when the user scrolls within about 800 px of the end (a Load more button is fine too). Stop when the loaded count reaches pagination.total or hasNextPage is false. A new search resets the list. Drop duplicate image_ids.
• Browse-all: the hosted gallery shows only the first page of all photos unless the organiser turns on show-all-photos. The public All Photos and Timeline endpoints return every photo, so agree with the organiser whether to offer browsing beyond page 1.
• Grid tiles use thumbnail_url, lazy-loaded, with their space reserved from width and height so rows don’t jump. Justified rows match the hosted gallery; any layout that keeps aspect ratios is fine.
• A tile that fails to load shows “Couldn’t load photo” and a Retry for that tile only.
• Retry a failed page load (network error or 5xx) up to 2 times with exponential backoff from 300 ms; a 400, 401, 403 or 404 will not change on retry. If it still fails, keep the photos already shown and offer a retry (the hosted gallery reloads the page).
• On 429, back off as Errors describes for background page loads. For a selfie upload, don’t retry automatically; ask the participant to wait a moment and try again.

​

Viewer

• Opens on tap. Shows img_url, never an original. Zoom (pinch, wheel, double-tap), swipe, Left/Right arrows, Escape to close. Covers the photos loaded so far.
• For selfie and bib results only, warm the loaded results’ img_urls in the background: start after about 1 s, 2 at a time (3 on a 4G connection), skip on Save-Data or 2G, pause while the tab is hidden.

​

Caching: what to keep, what not to build

• 9Pic already caches each search under its search ID. That is the cache. Do not hash selfies, invent cache keys, or store result pages in your own database; read pages through the backend with the saved ID.
• In the browser, keep only: the last search ID per event, the selfie thumbnail for that search, and optional UI preferences such as language.
• Use image URLs exactly as returned. Do not build URLs from image_id, change size segments, or add query strings.
• Do not store presigned download URLs (they expire after about an hour) or the API key anywhere. Clip status is read fresh while polling; only the last final status is saved (see Video clips).

​

Timeline

• Day list (first day selected by default), then an hour histogram, then a time window in 15-minute steps with 15, 30, 60 and 120 minute presets. With no hour picked, the window spans the hours that have photos. Each change updates the URL.
• Timeline times are the event’s local clock time stored as if it were UTC. Format every timestamp with timeZone: 'UTC' and build from/to the same way. Never convert to the viewer’s time zone, or every photo shifts by the viewer’s offset.
• Empty states: “No timestamped photos yet” for an event without timeline data; “No photos found for the selected time” for an empty window.

​

Video clips

• Start clips with a POST carrying the saved search ID and no file. If clipping is already processing or completed, the start just returns the current status, so a refresh can safely POST again. Do not read the status first to decide whether to start, because a job that never started reads as processing. Save the last final status (completed, no_matches, no_segments, failed, clip_failed) with the saved search: after a reload, a tab switch, or a remount, a saved no_matches / no_segments shows “No videos found” without a new POST; anything else POSTs as above.
• Then poll the status every 10 s while it is processing. A manual Refresh has a 30 s cooldown.
• Show: processing with progress, completed clips, and “No videos found” for no_matches / no_segments (don’t POST again after these: another POST runs clipping again). For failed / clip_failed show an error with Try again, which POSTs again with the same ID; if that fails too, offer a new selfie search. Send force_recreate=true only for completed clips that were deleted or expired, or a job stuck in processing.
• A 409 means the event’s video watermark isn’t ready yet: say clips are being prepared and to try again later. A 400 on a file-less start, for a search ID your backend saved, means no video data exists for that search: show “No videos found” (as the hosted gallery does), or offer a video search with a fresh selfie upload. Don’t branch on the message text.
• video_url is HLS. Use native playback on Safari and an HLS player elsewhere. When purchase_required is true (one flag on data for the whole response, not on each clip; the organiser sells clips), play them as watermarked previews labelled as such, and offer no download; clip sales are not available through the public API, so agree with the organiser how clips are sold. Otherwise offer download_url only when download_status is ready. Field details are on Video Clipping Search.

​

Free downloads

• When the organiser allows free downloads, the hosted gallery offers a download button on each tile and in the viewer, and Download all on selfie and bib results (zipped in batches of up to 20 MB or 100 files). These are the large preview images. Agree with the organiser whether to offer them.
• Paid unwatermarked originals go through your checkout and Sell Originals, never through the gallery directly.

​

Look and Feel (Optional)

• Header with the organiser’s logo and theme colour; event name, date and optional banner above the search. The public API returns no logo or theme colour, so supply your own assets or skip the header.
• Search actions as a sticky bottom bar on phones; large tap targets; a full-screen viewer.
• Any of these may be replaced by your own design system.

​

Sell Originals

​

Review Your App

​

Must have

​

Good to have

​

Out of Scope

• Import, process, and go-live are organiser pipeline endpoints. See Memories.
• 9Pic Checkout and payment-provider APIs. Payment is your own system.
• Flow, Certify, and Buzz have no public /ext/ API.
• To run your 9Pic account from an assistant instead of writing code, connect the 9Pic AI MCP server.

​

Related