Quickstart

Five minutes, three steps, and nothing at your origin changes. If you stop halfway, you have changed nothing.

1. Create a project

Sign in at https://app.picsoar.com and create a project. You get a project key that looks like prj_01H8XKQ2M7N4P5R6S7T8V9W0XY. It appears in every delivery URL, so it is public by design and is not a credential.

2. Register and verify an origin

Enter the hostname your images are already served from, plus an optional base path. Then publish the TXT record shown in the dashboard:

_picsoar.cdn.example.com  TXT  "picsoar-verify=..."

Verification checks the record and confirms the hostname does not resolve into private address space. Nothing is fetched from your origin, and no configuration reaches the edge, until this succeeds.

3. Change one URL

https://cdn.example.com/assets/products/shoe.jpg

becomes

https://cdn.picsoar.com/v1/prj_YOUR_KEY/card/products/shoe.jpg?v=8f2c1a

The path after the preset is relative to the base path you registered. Check that one image before changing the rest — it is the fastest way to catch a base-path mistake.

Confirm it worked

curl -sI -H 'Accept: image/webp' \
  https://cdn.picsoar.com/v1/prj_YOUR_KEY/card/products/shoe.jpg | grep -i 'content-type\|x-picsoar'

You should see:

content-type: image/webp
x-picsoar-preset: card@1
x-picsoar-format: webp
x-picsoar-decision: accept-webp
x-picsoar-cache: miss

Repeat without the Accept header and you will get image/jpeg andx-picsoar-format: source. That is the fallback working, not a failure.

If something is wrong

Every response carries x-picsoar-reason when it is not a normal delivery. Common ones:

• unknown-project — the key is wrong, or no origin is verified yet.
• origin-status:404 — your origin does not have that file at that path.
• path:unsupported-extension — only image extensions are served.
• query:unsupported-param:width — only ?v= is accepted.

Quote the x-request-id in a support email and we can find the exact request.