Picsha AI

Architecture Overview

Picsha AI is designed from the ground up for Serverless, Agentic, and Headless architectures. Understanding how we securely pool and isolate your media is critical.

The Organization (Workspace)

When you create an account on Picsha AI, you are placed into a default Personal Account. From there, you can optionally create or join dedicated Organizations for team collaboration.

  • All uploaded media assets, intelligent search vectors, and facial recognition databases are strictly bound to the active Organization context.
  • You can seamlessly switch between your Personal Account and Organizations using the dashboard switcher.

API Keys

Some platforms map API Keys to isolated "Sub-Environments" (like Dev/Staging). Picsha does not. Instead, keys are bound directly to your Organization Workspace, eliminating the headache of duplicating assets across environments and encouraging a single unified DAM (Digital Asset Manager).

The API accepts three kinds of credential:

  • Secret API Keys (sk_live_...): Your full Organization password. Unrestricted read, write, and administrative (hard delete) privileges, with no per-key scoping. Server-side only — never expose one in frontend code.
  • Session tokens: The short-lived JWT issued to a signed-in Picsha user. Scoped to that user and their active organization, and safe to use from a browser because it expires and belongs to the person holding it.
  • OAuth access tokens: Issued when a user connects an AI assistant to the hosted MCP endpoint. Automatically scoped to the signed-in user.

[!IMPORTANT] There is no browser-safe publishable key today. If your application's end users are not Picsha users, do not ship any Picsha credential to the client: proxy uploads through your own backend, hand out presigned upload URLs (GET /v1/assets/presigned), and mint signed delivery URLs server-side.

Scoping requests to your end users

An API key operates at the full scope of its Organization. For customer-facing, multi-user applications, pass the end user's identifier in the x-external-user-id header on every request so Picsha applies per-user isolation on top of the organization boundary.

Ingest attribution

While keys share one asset pool, every asset records which credential created it. At ingest, Picsha stamps the asset's metadata server-side with uploadSource (api_key, console, connector, sso, or system) and, for key-authenticated uploads, apiKeyId and apiKeyName. Client-supplied values for these keys are ignored at create time. The playground's upload dialog has an "Upload as" selector that re-signs the ingest with one of your keys server-side, so you can attribute uploads without leaving the console. Filter on them anywhere metadata is filterable — for example GET /v1/assets?metadataField=apiKeyName&metadataValue=prints%20app, or metadataField/metadataValue in search filters.

The AI Metadata Layer

Every image pushed through Picsha is piped asynchronously to AWS Rekognition and Amazon Bedrock.

  • Text detected in images is vectorized natively.
  • Object boundaries, facial bounding boxes, and EXIF camera models are extracted recursively.
  • The resulting vector embeddings are stored seamlessly in AWS OpenSearch, allowing your frontend users (or AI Agents) to search your library semantically.