Quickstart

This page walks through getting an API Key, installing the SDK, and uploading your first image. The same flow works against api.picora.me (global) or api.picora.cn (China deployment) — set the base URL accordingly.

Use the SDK

The recommended way to call Picora is the official @picora/sdk — it is typed, auto-retries rate limits, handles OAuth refresh, and covers 100% of the API. The curl / raw-HTTP snippets below are there for languages without an SDK yet or for quick shell testing.

1 · Create an API Key

1. Sign in at center.picora.me.
2. Open Integration → API Keys.
3. Click Create Key and pick the minimum permissions:
   • For an MCP read-only tool: tick media.read, kb.read, account.read, usage.read (or use the AI / MCP read-only preset).
   • For a creator tool that uploads: also tick media.write, kb.write (or use the Creator preset).
   • Avoid media.delete unless your tool genuinely deletes content.
4. Copy the sk_live_… value — it is shown once.

For the v0.13 legacy three-tier scopes (read / read_write / read_write_delete), see Authentication.

2 · Install the SDK

TypeScript / JavaScript

npm install @picora/sdk
# or
pnpm add @picora/sdk
# or
bun add @picora/sdk

Python (no official SDK yet — call HTTP directly)

pip install httpx

curl (no install needed)

You’ll need an OS-level curl ≥ 7.20 (any modern macOS / Linux / Windows ships one).

3 · Upload your first image

Each snippet uploads cat.jpg, then prints the public CDN URL.

TypeScript (recommended)

import { createPicoraClient, PicoraApiError } from '@picora/sdk'
import { readFileSync } from 'node:fs'

const picora = createPicoraClient({
  apiKey: process.env.PICORA_API_KEY!,
  // baseUrl defaults to 'https://api.picora.me' — override for the China deployment:
  // baseUrl: 'https://api.picora.cn',
})

try {
  const img = await picora.images.upload({
    file: readFileSync('cat.jpg'),
    filename: 'cat.jpg',
    contentType: 'image/jpeg',
    isPublic: true,
  })
  console.log(img.url)                    // https://media.picora.me/<nanoid>.jpg
} catch (err) {
  if (err instanceof PicoraApiError) {
    console.error(`API ${err.status} ${err.code}: ${err.message}`)
  } else {
    throw err
  }
}

Python

import os
import httpx

API_KEY = os.environ["PICORA_API_KEY"]
BASE = "https://api.picora.me"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

with open("cat.jpg", "rb") as fh:
    files = {"file": ("cat.jpg", fh, "image/jpeg")}
    r = httpx.post(f"{BASE}/v1/images", headers=HEADERS, files=files, timeout=30)

r.raise_for_status()
data = r.json()["data"]
print(data["url"])     # https://media.picora.me/<nanoid>.jpg

curl

curl -X POST https://api.picora.me/v1/images \
     -H "Authorization: Bearer $PICORA_API_KEY" \
     -F "file=@cat.jpg" \
     | jq -r .data.url

What’s next

• Read Authentication to understand when to use API Keys vs OAuth.
• Read Rate Limits before building anything that loops over thousands of files.
• Skim the full @picora/sdk reference — 30+ namespaces covering the entire API (images, videos, audio, docs, kbs, collections, aigc, billing, …).
• Try the interactive API Explorer — it lets you call any endpoint with your real Key.