# POUYAM Studio — independent library API and browser SDK

The same engines used by Studio are available individually for integration into
your own project. These APIs do not upload or edit your files remotely. POUYAM's
technology and artwork remain proprietary; integration does not transfer ownership.

## Discover, choose one, configure, render

1. `GET /api/studio/library` lists implemented libraries and SDK modules.
2. `GET /api/studio/library/{kind}?locale=en&limit=24&offset=0` returns items,
   total, nextOffset, groups and an exact settings JSON Schema. `locale` is `en`
   or `fa`, `limit` is 1–100. Optional `q` (up to 120 characters) and `group`
   filter before pagination. IDs are stable and independent of locale.
3. `GET /api/studio/library/{kind}/{id}?locale=fa` returns that item, defaults
   and schema. Unknown IDs return 404, never substitute a different design.
4. `POST /api/studio/library/{kind}/{id}` with the settings object returns a
   validated, default-completed configuration. Unknown properties, bad types,
   non-finite numbers, invalid colors and out-of-range values return 422.
5. Import only the SDK you use. REST and SDK responses permit cross-origin
   access without credentials. Nothing runs on your media until your code calls it.

Try the framework-free [working HTML demo](library-demo.html). To check an API on
another origin, open `library-demo.html?api=http://127.0.0.1:3110` from another local
web server. Configuration responses contain `settings` that can be passed directly
to the corresponding SDK; the item ID remains a separate argument.

Base origin: `https://www.pouyam.com`. For development, substitute your local
origin. No API key is needed for these public, side-effect-free tools. Full use
of the Studio application follows its existing sign-in flow.

| kind | What is actually available | Independent use |
|---|---|---|
| elements | 200 transparent designs in 20 families; six palettes | SVG, local PNG export, deterministic motion transforms |
| transitions | 50 original transitions in 10 collections | Canvas2D composition of two decoded frames |
| motions | 24 layer movements | Time-dependent transform/reveal values |
| backgrounds | 18 existing procedural designs, including 16 editor color effects | Deterministic Canvas2D frames, six palettes, custom colors |
| templates | 12 EN/FA commercial compositions | Original background, grade and independent editable text layers |

The 18 background IDs include the studio's `sunrise` and `paper` designs; they
are not falsely counted as extra layer motions. Motion and transition IDs are
different namespaces. Library features are **not** additional recipe/1 steps.
Existing photo grading, crop, text, retouch, video trim, PDF, document and sheet
operations remain available through `/api/studio/recipe-link` and its recipe schema.

## One transparent element

```js
const base = 'https://www.pouyam.com';
const element = await import(`${base}/api/studio/sdk/elements`);
const settings = {
  color: '#65d9c5', accent: '#dbfff1', contrast: 1.2, resolution: 1024,
  motion: 'pulse', motionDuration: 3, motionDelay: 0,
  motionSpeed: 1, motionIntensity: 0.5, motionRepeat: true
};
const svgText = element.svg('identity-01', settings);
const pngBlob = await element.png('identity-01', settings, abortSignal);
const transform = element.frame('identity-01', 0.5, settings);
// pngBlob is transparent. A PNG is a still image; motion is a separate time function.
```

`GET /api/studio/library/elements/identity-01/svg?color=%2365d9c5&accent=%23dbfff1&contrast=1.2&resolution=1024`
returns custom transparent SVG, with correct `image/svg+xml` MIME and CORS.
Only color, accent, contrast and resolution are accepted on this SVG endpoint.
An encoded `#` is required in URL colors. Default PNG and WebP URLs are returned
in the item, with no need to download all 200 assets. For Canvas export across
origins, use the CORS SVG endpoint or the SDK-generated Blob rather than assuming
every static asset host permits canvas access.

## One transition on your canvas

```js
const { createRenderer } = await import(
  'https://www.pouyam.com/api/studio/sdk/transitions'
);
const renderer = createRenderer();
const settings = {
  duration: 1.2, intensity: 1.15, opacity: 0.8,
  contrast: 1.2, color: '#e8bc72'
};
// ctx is a CanvasRenderingContext2D; from and to are decoded CanvasImageSource.
renderer.render(ctx, from, to, 'damped-spring', 0.6, settings);
// 0 seconds = exact first frame; duration seconds = exact second frame.
// Call repeatedly with your own clock; seeking is deterministic.
renderer.dispose();
```

Allocate one renderer per concurrent transition, reuse it across frames, dispose
when finished. The caller controls canvas dimensions, decoding, clip selection,
audio synchronization, and recording/export. This API is not a server MP4 encoder.
Use origin-clean source images/videos: cross-origin media without valid CORS can
taint a canvas and prevent export. Duration is 0.01–3 seconds. In Studio's actual
timeline, the window is centered on a touching cut, capped by both clip lengths;
the SDK does not impose a timeline or change your media length. Color changes
affect the relevant light/graphic portions; some signature brush/paper colors
are deliberately fixed. Models approximate camera/material motion in 2D.

## Layer motion and generated background

```js
const motion = await import('https://www.pouyam.com/api/studio/sdk/motions');
const m = motion.frame('spring', 0.5, {
  motionDuration: 1, motionRepeat: false, motionIntensity: 0.8
});
// m.x, m.y are fractions of layer bounds; rotation is radians.
// Apply scaleX/scaleY, opacity, reveal and blur in your own compositor.
// Typewriter/words need your text segmentation; wipe/iris need your clip geometry.

const background = await import('https://www.pouyam.com/api/studio/sdk/backgrounds');
background.render(ctx, 'aurora', 0.5, {
  palette: 'jade', seed: 42, density: 45, energy: 55, speed: 1
});
// Uses ctx.canvas.width/height; loops every six seconds with integer speed 1–3.
```

Use the same seconds for every layer. Respect reduced-motion preferences in your
application: stop autoplay and render a chosen still frame. Do not load all SDKs
at startup. Modules have no framework dependency or automatic network/media calls.
SVG/PNG functions run locally; browser APIs are required for PNG/transition scratch
canvases. `AbortSignal` for PNG is checked around rasterization; it cannot interrupt
an in-progress synchronous browser decode. `frame` and `render` reject negative or
non-finite seconds. Settings are validated against the REST schema.

## Editable templates

```js
const design = await fetch(
  'https://www.pouyam.com/api/studio/library/templates/coffee-house?locale=en'
).then(r => r.json());
// design.item.assetUrl: original background (not flattened preview).
// design.item.grade: editable adjustments.
// design.item.layers: four independently editable text layers.
// Coordinates are normalized; type sizes assume a 1080-edge composition.
```

Template previews are 4:5 crops and are not editable compositions themselves.
Load the original background, compute a centered 4:5 crop, apply the grade and
layers. Font families are supplied as metadata; the SDK does not silently load
external fonts. Supply licensed fonts and await their loading in your compositor.

## Agents and errors

MCP adds `list_studio_library` (kind, optional locale/q/group/offset/limit) and
`get_studio_library_item` (kind, id, optional locale). Responses have relative asset
and SDK URLs: resolve them against the base origin. Use IDs from the catalog,
never invent IDs or suggest unsupported recipe/1 operations.

400: invalid query/JSON; 404: unknown kind or ID; 413: request over 64 KiB;
422: invalid settings; 429: too many SVG/configuration requests (60/minute,
1000/day per address, separate buckets). Honor `Retry-After`. Read catalogs are
cached for five minutes; version 1 identifies the contract. No remote generation,
cloud project saving, background removal or paid service is activated by this API.

### فارسی

هر ابزار شناسهٔ مستقل دارد. از فهرست شناسه را انتخاب کنید، جزئیات و محدودهٔ
تنظیمات را بگیرید و فقط ماژول همان ابزار را وارد پروژه کنید. عناصر خروجی شفاف
SVG و PNG دارند؛ موشن PNG را متحرک نمی‌کند و باید با زمان مشترک رندر شود.
ترنزیشن روی دو فریمِ آماده در بوم مرورگر اجرا می‌شود؛ ساخت ویدیو روی سرور
یا ارسال فایل انجام نمی‌شود. قالب‌ها تصویر اصلی و نوشته‌های جداگانه دارند.
تنظیمات نامعتبر خطا می‌دهند و به ابزار دیگری تبدیل نمی‌شوند.
