# POUYAM Studio — guide for AI assistants

POUYAM Studio (https://www.pouyam.com/studio) edits photos, videos, PDFs, Word
documents and spreadsheets **inside the user's own browser**. This guide tells
an AI assistant (ChatGPT, Claude, Gemini, Cursor, Codex, or any agent) how to
turn a request such as *"edit this video in POUYAM"* into a ready-to-apply edit.

- Recipe format: `pouyam.studio.recipe/1`
- JSON Schema: https://www.pouyam.com/studio-ai/recipe.schema.json
- MCP server (Streamable HTTP): `https://www.pouyam.com/mcp`
- HTTP endpoint: `POST https://www.pouyam.com/api/studio/recipe-link`
- Capabilities (live values): `GET https://www.pouyam.com/api/studio/recipe-link`
- Setup page for people: https://www.pouyam.com/api/studio

---

## 1. How it works

1. The user describes the edit ("make this photo cinematic and square", "cut
   seconds 3–12 of my clip and add a caption", "delete page 4 of this PDF").
2. You write a **recipe**: a small JSON list of edit steps.
3. You give the user a **Studio link** (or the recipe itself).
4. The user opens the link. Studio lists every step. The user chooses the file
   on their device, Studio applies the steps, and the user reviews and exports.

You never receive, upload or download the user's file. Studio does not upload
it either; it stays in the browser. A recipe contains instructions only.

### Three ways to deliver a recipe

| You have | Do this |
|---|---|
| The POUYAM MCP server connected | Call `create_studio_link` with the recipe and share the returned `link`. |
| Web/HTTP tool access | `POST` the recipe to `/api/studio/recipe-link` and share the returned `link`. |
| No tools | Show the recipe JSON in one code block and tell the user: open https://www.pouyam.com/studio, click **"Have an edit recipe… Paste it here"** (or press Ctrl+V on the page), paste, review, choose the file. |

Do not hand-build `#recipe=` links yourself; the encoding is easy to get wrong.
Use a tool or the paste flow.

---

## 2. Recipe shape

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Short name the user will see",
  "target": "photo | video | pdf | document | sheet",
  "steps": [ { "op": "…", "...": "…" } ]
}
```

Rules:

- `format` must be exactly `pouyam.studio.recipe/1`.
- One recipe edits one file. `target` decides which steps are allowed.
- 1 to 40 steps, applied in order. Up to 16 KB.
- All text is plain text (no HTML, no Markdown). Persian, Arabic and other RTL
  text is supported.
- Pages are **1-based** in the current order. Times are **seconds**.
- Unknown steps, unknown preset names and out-of-range numbers are skipped or
  clamped, and the user sees a note. Studio never runs anything else.

---

## 3. Steps by target

### photo

| op | fields | notes |
|---|---|---|
| `look` | `preset`, `strength` 0–100 (default 100) | presets: `natural`, `cinematic`, `editorial`, `portrait`, `fashion`, `film`, `mono`, `travel`, `urban`, `night`, `warm`, `cool`, `vintage`, `moody` (call capabilities for the live list) |
| `adjust` | `values`: object of the fields below | exposure −2…2; contrast, highlights, shadows, whites, blacks, temperature, tint, vibrance, saturation, texture, clarity, dehaze, vignette −100…100; sharpen, denoise, grain 0…100 |
| `retouch` | `recipe` | `natural-skin`, `studio-clean`, `soft-glow`, `beauty-detail`, `low-light` |
| `adjust` (portrait) | `values`: skinSmooth, redness, shine, eyeBright, teethWhite 0…100 | subtle values (10–40) look natural |
| `lut` | `id`, `strength` 0–100 | `neutral`, `teal-orange`, `kodak-warm`, `bleach`, `moon`, `mono-lut` |
| `auto` | `mode`: `color` or `enhance` | reads the photo's tones in Studio |
| `crop` | `aspect` | `1:1`, `4:5`, `9:16`, `16:9`, `3:2`, `2:3`, `4:3`, `21:9` (centered) |
| `rotate` | `degrees`: 90, 180, 270 | clockwise |
| `flip` | `axis`: `horizontal` or `vertical` | |
| `straighten` | `degrees` −15…15 | |
| `text` | `text` (≤280), `position` top/center/bottom, `size` 12–240, `color` `#rrggbb`, `weight` 300–900, `background` true/false | one layer per step |

### video

`look`, `adjust`, `lut`, `retouch`, `auto`, `text` as above (applied to the
first clip), plus:

| op | fields |
|---|---|
| `trim` | `start`, `end` (seconds of the source; keeps that range) |
| `speed` | `rate` 0.25–4 |
| `fade` | `in`, `out` seconds (0–10, at most half the clip) |
| `volume` | `level` 0–1 |
| `caption` | `start`, `end`, `text` (≤200) |
| `rotate` | `degrees` 90, 180, 270 |

Video crop/aspect changes are not available through recipes yet.

### pdf

| op | fields |
|---|---|
| `pdf.rotate` | `pages`: `"all"` or `[1, 3]`, `degrees` 90/180/270 |
| `pdf.delete` | `pages`: `[4, 5]` (a PDF keeps at least one page) |
| `pdf.reorder` | `order`: every page exactly once, e.g. `[2, 1, 3]` |
| `pdf.note` | `page`, `text` (≤1000), `x`, `y` (0–1 from top-left), `size` 8–96, `color` |

Steps run in order, so page numbers after a delete or reorder refer to the new order.

### document (DOCX, TXT, Markdown, HTML)

| op | fields |
|---|---|
| `doc.replace` | `find`, `replace`, `all` (default true) — text only, never markup |
| `doc.append` | `text`, `style`: `paragraph` or `heading` |
| `doc.prepend` | `text`, `style` |

A newline in `text` starts a new paragraph.

### sheet (XLSX, CSV)

| op | fields |
|---|---|
| `sheet.set` | `sheet` (1-based, default 1), `cell` like `B3`, `value` (text or number) |

Formulas (`=SUM(...)`) are refused for safety; write values.

---

## 4. Examples

### Photo — cinematic Instagram post

User: *"این عکس رو سینمایی کن، مربعی برای اینستاگرام، پایینش بنویس «سفر به شیراز»"*

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Shiraz — cinematic square",
  "target": "photo",
  "steps": [
    { "op": "look", "preset": "cinematic", "strength": 85 },
    { "op": "adjust", "values": { "contrast": 12, "shadows": 18, "vignette": -20 } },
    { "op": "crop", "aspect": "1:1" },
    { "op": "text", "text": "سفر به شیراز", "position": "bottom", "size": 72, "color": "#ffffff", "weight": 800, "background": false }
  ]
}
```

### Photo — natural portrait retouch

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Natural portrait",
  "target": "photo",
  "steps": [
    { "op": "retouch", "recipe": "natural-skin" },
    { "op": "adjust", "values": { "eyeBright": 20, "teethWhite": 15, "exposure": 0.15 } },
    { "op": "crop", "aspect": "4:5" }
  ]
}
```

### Photo — moody black and white

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Moody B&W",
  "target": "photo",
  "steps": [
    { "op": "look", "preset": "mono" },
    { "op": "adjust", "values": { "contrast": 30, "clarity": 20, "grain": 18, "vignette": -30 } }
  ]
}
```

### Video — short reel cut

User: *"Cut my video from 0:03 to 0:12, make it a bit faster, fade in and out, warm colors, caption 'Tehran nights' at the start."*

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Tehran nights reel",
  "target": "video",
  "steps": [
    { "op": "trim", "start": 3, "end": 12 },
    { "op": "speed", "rate": 1.25 },
    { "op": "fade", "in": 0.5, "out": 0.8 },
    { "op": "look", "preset": "warm", "strength": 70 },
    { "op": "caption", "start": 0, "end": 2.5, "text": "Tehran nights" }
  ]
}
```

### Video — mute and grade for a presentation

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Silent product clip",
  "target": "video",
  "steps": [
    { "op": "volume", "level": 0 },
    { "op": "lut", "id": "teal-orange", "strength": 60 },
    { "op": "text", "text": "POUYAM", "position": "top", "size": 48, "color": "#ffffff", "weight": 700, "background": true }
  ]
}
```

### PDF — clean up a scan

User: *"صفحه ۲ این پی‌دی‌اف برعکسه، صفحه آخر (۶) رو حذف کن، روی صفحه اول بنویس «تأیید شد»"*

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Scan cleanup",
  "target": "pdf",
  "steps": [
    { "op": "pdf.rotate", "pages": [2], "degrees": 180 },
    { "op": "pdf.delete", "pages": [6] },
    { "op": "pdf.note", "page": 1, "text": "تأیید شد", "x": 0.7, "y": 0.08, "size": 22, "color": "#c62828" }
  ]
}
```

### Word — update a contract

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Contract 2026 update",
  "target": "document",
  "steps": [
    { "op": "doc.replace", "find": "2025", "replace": "2026" },
    { "op": "doc.replace", "find": "Acme Ltd", "replace": "POUYAM Co." },
    { "op": "doc.append", "text": "Signed digitally on 28 September 2026.", "style": "paragraph" }
  ]
}
```

### Spreadsheet — fill a report

```json
{
  "format": "pouyam.studio.recipe/1",
  "title": "Q3 figures",
  "target": "sheet",
  "steps": [
    { "op": "sheet.set", "cell": "A1", "value": "Quarter" },
    { "op": "sheet.set", "cell": "B1", "value": "Revenue" },
    { "op": "sheet.set", "cell": "A2", "value": "Q3" },
    { "op": "sheet.set", "cell": "B2", "value": "128400" }
  ]
}
```

---

## 5. How to talk to the user

- Reply in the user's language.
- Say the edit is **ready to apply**, never that it is already done.
- Summarize the steps in one or two lines, then give the link (or the recipe
  block with the paste instructions).
- If the request needs something recipes cannot do (object removal, background
  replacement, generating new images, video crop to a new aspect, formulas),
  say so plainly and offer the closest recipe, or tell the user which Studio
  panel to open by hand.
- Ask one short question only when the request is ambiguous in a way that
  changes the result (for example, which pages to delete).

Example reply:

> Your edit is ready: trim to 0:03–0:12, 1.25× speed, soft fades, warm look and
> a "Tehran nights" caption. Open this link, choose the video, check the result
> and export: https://www.pouyam.com/studio#recipe=…

---

## 6. Privacy and safety

- Recipes carry instructions only: no files, URLs, scripts or markup. Studio
  rejects anything else.
- The link keeps the recipe after `#`, which browsers do not send to servers.
- The user always sees the steps and chooses the file; Studio never applies a
  recipe or exports on its own.
- The MCP server and HTTP endpoint store nothing and are rate limited.

## 7. Connecting the MCP server

- **Claude (web/desktop):** Settings → Connectors → Add custom connector →
  `https://www.pouyam.com/mcp`.
- **ChatGPT:** Settings → Apps & Connectors → Advanced → Developer mode →
  Create → MCP server URL `https://www.pouyam.com/mcp`, no authentication.
- **Cursor:** add to `mcp.json`:
  `{ "mcpServers": { "pouyam-studio": { "url": "https://www.pouyam.com/mcp" } } }`
- **Claude Code:** `claude mcp add --transport http pouyam-studio https://www.pouyam.com/mcp`

Tools: `get_studio_capabilities` (no input) and `create_studio_link`
(`{ "recipe": { … } }`, returns `link`, `steps`, `warnings`).