Skip to content
  • Follow System
  • English
  • 中文

API Reference

The complete, always-current reference for every endpoint — request/response schemas, parameters, and a try-it-out console — is the interactive API playground (powered by Scalar, generated from the live OpenAPI spec).

The map below groups every API domain and links each to the doc that explains it. The detailed prose pages in this section (Upload, Images, Videos, Audio, Docs, KB Sync, Errors) go deep on the core media APIs; for everything else, the product docs give the concepts and the playground gives the exact endpoints.

API domains

Media & resources

DomainPathLearn more
Images/v1/imagesImages API · Upload
Videos/v1/videosVideos API
Audio/v1/audioAudio API
Documents/v1/docsDocs API
Unified media/v1/mediaListing + batch delete across types
Resumable upload/v1/uploadsTUS upload
Custom domains/v1/domainsServe media on your own domain
Storage tiering/v1/storage-tierStorage tiering
Watermark/v1/watermarkWatermark templates

Collections & knowledge bases

DomainPathLearn more
Collections/v1/collectionsCollections
Collection types/v1/collection-typesCollection types
Episodes/v1/collections/{id}/episodesEpisodes
Knowledge bases/v1/kbsKB Sync v1 vs v2

AI generation

DomainPathLearn more
AIGC projects & generation/v1/aigc/*AIGC
AI image tools/v1/ai/*AI image tools
Agreements (AIGC terms)/v1/agreements/*Consent for AI features

Publishing

DomainPathLearn more
Published pages/v1/published-pagesPublishing
Multi-platform publish/v1/publish/*Publishing

Billing & credits

DomainPathLearn more
Billing/v1/billing/*Plans & billing
Credit wallet/v1/credit/*Credit wallet
Campaigns & coupons/v1/campaigns, /v1/couponsPromotions
Notifications/v1/notificationsNotifications

Teams

DomainPathLearn more
Organizations/v1/orgs/*Teams & organizations

Account & authentication

DomainPathLearn more
Authentication/v1/auth/*Security
User & profile/v1/user/*, /v1/me/*Account
API keys/v1/api-keysAPI Keys
OAuth 2.1 provider/v1/oauth/*Authorized apps
OAuth device flow/v1/oauth/device*Developer auth

Analytics & data

DomainPathLearn more
Insights/v1/insights/*Insights
Backup & export/v1/backup/*Backup
Migration/v1/migration/*Migration

Integrations & system

DomainPathLearn more
MCP catalog/v1/mcp/*MCP Marketplace
Support tickets/v1/ticketsIn-dashboard support
Health/healthService status
Webhooks/webhooks/{provider}Provider-signed callbacks (inbound)

Admin endpoints (/v1/admin/*) require is_admin and are internal operations — not part of the public API.

Base URLs

PlatformAPI baseDefault media CDN
Overseas (CF)https://api.picora.mehttps://media.picora.me
Mainland (Aliyun)https://api.picora.cnhttps://media.picora.cn

The two platforms have fully isolated databases. An account on one is not accessible from the other. See FAQ → why two platforms?.

Authentication

Picora supports two authentication mechanisms (described in the user-facing API Keys guide and authorized OAuth apps).

API Key (Bearer sk_live_...)

Used by tool clients (PicGo / Moraya / your scripts) and stdio MCP. Set on every request:

Authorization: Bearer sk_live_abcdef0123456789...

JWT (web dashboard)

Browser sessions get JWT access tokens (15-min lifetime) + refresh token cookies (7-day, httpOnly). The dashboard handles refresh transparently. Direct API consumers should prefer API Keys, not JWTs.

OAuth 2.1 (HTTP MCP, v0.14+)

Hosted MCP server at mcp.picora.me uses OAuth 2.1 with refresh token rotation. See MCP → Remote MCP.

Common response shape

All Picora API endpoints return a uniform JSON envelope.

Success:

{ "success": true, "data": { ... } }

Error:

{ "success": false, "error": "Human-readable description", "code": "MACHINE_CODE", "meta": { ... } }

code is the machine-readable identifier (see errors). meta is endpoint-specific structured context (e.g., { "type": "img_storage", "used": 104857600, "limit": 104857600 } for QUOTA_EXCEEDED).

Pagination

List endpoints use cursor pagination (not offset). Pass the cursor from the previous response’s nextCursor field; an empty / absent cursor means the first page.

Terminal window
curl "https://api.picora.me/v1/images?limit=20"
# → { "items": [...], "nextCursor": "eyJpZCI6Il..." }


curl "https://api.picora.me/v1/images?limit=20&cursor=eyJpZCI6Il..."
# → { "items": [...], "nextCursor": null }   // last page

Maximum limit per request is 50.

Rate limiting

Per-tier rate limits (introduced in v0.12.0):

TierEndpointsLimit (per minute)
readGET /v1/images, GET /v1/media, GET /v1/docs/*, GET /v1/admin/*600
mutationPATCH / DELETE operations on resources120
uploadPOST /v1/images, POST /v1/videos, POST /v1/audio, POST /v1/docs60

Excess requests return HTTP 429 with Retry-After header. See errors → RATE_LIMITED.

ID format

All resource IDs use nanoid (URL-safe). Two lengths:

ResourceLengthReason
Images11 chars (e.g., xK9mR2pQ7vB)Used in public CDN URLs; 11 chars balances brevity with collision resistance
Other (videos / audio / docs / users / API keys)21 chars (default nanoid)Internal IDs, more entropy

API keys use a special format: sk_live_ prefix + 32-char nanoid = 40 chars total.

Timestamps

All timestamps are returned in ISO 8601 UTC format:

{ "createdAt": "2026-04-27T08:00:00.000Z" }

Clients should format to user’s local timezone.

CORS

Browser requests from the picora-center dashboard work by default. API-Key-authenticated requests bypass Origin checks (this fix, v0.12.0+, lets Tauri-based desktop apps like Moraya call the API directly).

Versioning

The current API version is /v1/ and is stable. Breaking changes will introduce /v2/; the old version remains supported for at least 12 months after /v2/ ships.