Images

Images are Picora’s flagship resource type. Upload from the dashboard, via API Key, or from any of the supported tools.

Quick upload via dashboard

1. Open Library → Images
2. Drag a file onto the upload zone, or click Upload
3. Pick public or private visibility (default: public)
4. Wait for upload (typically <3 seconds)
5. Copy the external link — that’s the public URL you can paste anywhere

Supported formats

Format	Extension	Max size	Notes
JPEG	.jpg .jpeg	per plan limit	Most common; lossy compression
PNG	.png	per plan limit	Lossless; preserves transparency
WebP	.webp	per plan limit	Modern; smaller than JPEG/PNG
GIF	.gif	per plan limit	Animated GIFs supported
SVG	.svg	2 MB	Sanitized on upload (script / event attributes stripped)
AVIF	.avif	per plan limit	Cutting-edge; smaller than WebP
HEIC	.heic	per plan limit	Auto-converted to JPEG

Per-plan size limits are in plan comparison.

Upload via API

curl -X POST https://api.picora.me/v1/images \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F file=@photo.jpg \
  -F isPublic=true \
  -F tags='["travel","2026"]'

Response:

{
  "success": true,
  "data": {
    "id": "xK9mR2pQ7vB",
    "url": "https://media.picora.me/xK9mR2pQ7vB.jpg",
    "filename": "photo.jpg",
    "sizeBytes": 524288,
    "isPublic": true,
    "tags": ["travel", "2026"],
    "createdAt": "2026-04-27T08:00:00Z"
  }
}

The id is an 11-character nanoid for stable external links. The full reference is in API Reference → Images.

Listing your images

GET /v1/images?cursor=&limit=20&tag=travel

Returns paginated metadata — see API Reference → Images for query parameters.

In the dashboard, the Library page handles pagination automatically with infinite scroll.

Visibility: public vs private

Setting	Behavior
isPublic = true (default)	URL https://media.picora.me/{id}.{ext} accessible without auth (subject to hotlinking rules)
isPublic = false	URL returns 401 Unauthorized for anonymous requests; only your dashboard / API Key can fetch

Switch visibility at any time from the dashboard’s image detail page.

CDN cache

After flipping a public image to private, the CDN edge cache may serve the old public version for up to 24 hours. Picora purges the cache automatically, but third-party CDNs / copies you’ve shared elsewhere can’t be undone retroactively.

Tags

Tags help you organize images. Each image can have up to 10 tags of up to 32 characters each.

curl -X PATCH https://api.picora.me/v1/images/{id} \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tags": ["travel", "2026", "italy"]}'

Filter the listing by tag with ?tag=italy.

Deletion

curl -X DELETE https://api.picora.me/v1/images/{id} \
  -H "Authorization: Bearer sk_live_..."

Or click Delete on the dashboard image detail page.

Deletion:

• Removes the row from img_images table
• Removes the file from object storage (R2 / OSS / COS)
• Decrements quota:img_storage:{userId} immediately
• Purges CDN cache (best-effort, may take 1-2 minutes globally)

Irreversible

Deletion is permanent. There’s no trash / recycle bin. Make sure you no longer need the file before deleting.

Common issues

“413 Payload Too Large” — file exceeds your plan’s size limit. Compress the image (use squoosh.app) or upgrade.

“403 QUOTA_EXCEEDED: img_storage” — total stored bytes hit your plan’s limit. Delete unused images or upgrade.

Upload appears to succeed but image isn’t visible — check isPublic setting; check CDN cache (try with cache-bust query like ?v=2).

External link returns 404 — the image was deleted. URLs are not reused; once gone, always gone.

Related

• API Reference — Images — full endpoint reference
• API Keys — for tool / programmatic uploads
• Quota overview
• Integration tools — PicGo, Moraya, Typora, Obsidian