Skip to content

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.

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

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

Python (no official SDK yet — call HTTP directly)

Terminal window
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

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 {
  // v0.1.0 SDK exposes images.list/get/delete; multipart upload arrives in v0.2.
  // For now, upload via the raw fetch helper or the curl example below; this snippet lists the result.
  const page = await picora.images.list({ pageSize: 5 })
  for (const img of page.items) console.log(img.url)
} 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

Terminal window
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