Pictwo SDK

Typed helpers for generating Pictwo image URLs — from the live hosted API, the jsDelivr CDN, or your own static files. One small API, three providers.

Installation

The SDK ships as three packages. Most apps only need @pictwo/core.

pnpm add @pictwo/core
# optional helpers
pnpm add @pictwo/faker @faker-js/faker
pnpm add @pictwo/images          # portable image assets + manifest

@pictwo/core

pictwo is a ready-made instance bound to the live hosted API. Use createPictwo(config) for a custom host or a different provider.

import { pictwo } from '@pictwo/core'

pictwo.image.url({ width: 800, height: 600 })
// https://pictwo.toneflix.net/800/600

pictwo.image.avatar({ width: 200, height: 200 })
// https://pictwo.toneflix.net/category/avatar/200/200

pictwo.image.fashion({ width: 800, height: 600, seed: 'home-card' })
// https://pictwo.toneflix.net/category/fashion/800/600?seed=home-card

pictwo.image.byId('20001', { width: 400, height: 300 })
// https://pictwo.toneflix.net/id/20001/400/300

pictwo.image.seed('hero', { width: 1200, height: 600 })
// https://pictwo.toneflix.net/seed/hero/1200/600

Image API

pictwo.image.url(options?)
pictwo.image.byCategory(category, options?)
pictwo.image.byId(id, options?)
pictwo.image.seed(seed, options?)
// one shortcut per shipped category:
pictwo.image.avatar / fashion / fabric / product / design / nature / …

Image options

interface ImageOptions {
  seed?: string | number
  id?: string
  width?: number
  height?: number
  size?: 'avatar' | 'thumb' | 'card' | 'portrait' | 'cover' | 'og' | string
  format?: 'jpg' | 'jpeg' | 'png' | 'webp' | 'avif'
  filters?: string[]               // e.g. ['greyscale', 'blur:4']
  fallback?: 'original' | 'nearest' | 'throw'
}

Size presets

Preset	Dimensions
`avatar`	128×128
`thumb`	256×256
`card`	400×400
`portrait`	600×800
`cover`	1200×600
`og`	1200×630

pictwo.image.url({ size: 'og' })                       // → /1200/630
pictwo.image.url({ width: 800, height: 600, format: 'webp' })  // → /800/600.webp
pictwo.image.url({ width: 800, height: 600, filters: ['greyscale', 'blur:4'] })
// → /800/600?filters=greyscale,blur:4

Providers

hostedThe live API with runtime Sharp processing default.

createPictwo({ source: { driver: 'hosted', baseUrl: 'https://pictwo.toneflix.net' } })

jsdelivrStatic assets from the published @pictwo/images package. Requires a manifest.

import manifest from '@pictwo/images/manifest.json'

const pictwo = createPictwo({
  source: { driver: 'jsdelivr', packageName: '@pictwo/images', version: '1.0.0' },
  manifest,
})

pictwo.image.fashion({ seed: 'home-card' })
// https://cdn.jsdelivr.net/npm/@pictwo/[email protected]/img/fashion/original/model-001.jpg

pictwo.image.fashion({ seed: 'home-card', size: 'card' })
// https://cdn.jsdelivr.net/npm/@pictwo/[email protected]/img/fashion/400x400/model-001.webp

localStatic paths served from your own app.

createPictwo({ source: { driver: 'local', baseUrl: '/pictwo/images' }, manifest })
// /pictwo/images/fashion/original/model-001.jpg

Nearest sizing

Static providers only serve pre-generated variants. The jsdelivr provider snaps any requested width/height to the nearest available variant by default, so you always get a real file.

jsdelivr.image.fashion({ width: 300, height: 300 })
// → .../fashion/400x400/model-001.webp   (nearest variant)

// opt local into the same behaviour:
local.image.fashion({ width: 300, height: 300, fallback: 'nearest' })

fallback	Behaviour when the exact variant is missing
`nearest`	snap to the closest available variant (jsdelivr default)
`original`	serve the full-size original (local default)
`throw`	raise a clear error

@pictwo/faker

A Faker.js image module backed by Pictwo. Drop it onto faker:

import { faker } from '@faker-js/faker'
import { pictwoImage } from '@pictwo/faker'

export const fake = { ...faker, image: pictwoImage() }

fake.image.url()             // https://pictwo.toneflix.net/640/480
fake.image.avatar()          // https://pictwo.toneflix.net/category/avatar/128/128
fake.image.africanFashion()  // https://pictwo.toneflix.net/category/african-fashion/640/480
fake.image.urlLoremFlickr({ category: 'fashion', width: 320, height: 240 })
// https://pictwo.toneflix.net/images/fashion?w=320&h=240

There is one method per shipped category. Hyphenated slugs become camelCase, e.g. african-fashion → africanFashion. urlPicsumPhotos() also maps Faker's grayscale/blur options onto filters. Unsupported Faker methods throw a clear Not implemented error.

@pictwo/images

The portable asset package: category originals, generated variants, and a deterministic manifest.json. Manage it from the repo root:

pnpm pictwo:images:generate    # generate scaled variants (Sharp)
pnpm pictwo:images:manifest    # rebuild manifest.json
pnpm pictwo:images:build       # generate + manifest
pnpm pictwo:images:sync        # copy originals → storage/app/public/images
pnpm pictwo:images:clean       # remove generated variant folders

CDN delivery — `?cdn`

Add ?cdn to any image route on the hosted API to skip runtime processing. The API resolves the matching jsDelivr URL and 302-redirects straight to it, so it works as a drop-in <img> source.

GET https://pictwo.toneflix.net/category/fashion/400/400?cdn
→ 302 Location: https://cdn.jsdelivr.net/npm/@pictwo/images@x/img/fashion/400x400/…webp

GET https://pictwo.toneflix.net/id/20001/800/600?cdn
GET https://pictwo.toneflix.net/seed/hero/1200/600?cdn

<img src="https://pictwo.toneflix.net/category/fashion/400/400?cdn" />

The same route shapes as the REST API are supported: /{w}/{h}, /id/…, /seed/…, and /category/…. CDN variants are served as webp by default.