ppl.studio

API reference

The public ppl.studio API. One per-user key does everything the dashboard does — personas, uploads, images, scripts, storyboards, workflow runs, video and social — JSON in, JSON out.

Getting started

One base URL, one key, one response envelope. Every /api/v1 route takes the same key and sees only your own data.

Base URL

https://ppl.studio

Authenticate

x-api-key: ppl_live_…
# or
Authorization: Bearer ppl_live_…

Quickstart

# 1. Mint a key in the dashboard: Account → API keys  (ppl_live_…)
# 2. Ask what it may do:

curl https://ppl.studio/api/v1/account \
  -H "x-api-key: ppl_live_xxx"

# → { "ok": true, "data": { "plan": "creator", "images": { … }, "video": { "allowed": true, … } } }

Mint and revoke keys in the dashboard under Account → API keys. A key is shown once — store it securely. A key that is present but invalid or revoked is a 401; it never falls back to a browser session.

Also

  • OpenAPI 3.1 spec — every endpoint below, to generate a client from.
  • MCP server — this API as tools for AI assistants: hosted at https://ppl.studio/mcp (sign in with OAuth — claude.ai, ChatGPT, Cursor), or local via npx to save results to your disk. The Claude skill teaches the workflows.
  • API overview — what you can build, and a five-call quickstart from a product page to an MP4.

A video, end to end

# Start a run — it works hands-off up to the priced preview, then waits
curl -X POST https://ppl.studio/api/v1/flows \
  -H "Authorization: Bearer ppl_live_xxx" -H "content-type: application/json" \
  -d '{ "preset": "creator-ugc-video", "creatorSlug": "maya",
        "briefSource": { "mode": "url", "value": "https://shop.example/serum" } }'
# → { "ok": true, "data": { "runId": "…" } }

# Poll it; data.next says what it waits on, data.estimate is the price
curl https://ppl.studio/api/v1/flows/$RUN -H "Authorization: Bearer ppl_live_xxx"
# → { …, "awaiting": "gate", "next": { "action": "approve", … }, "estimate": { "usd": 0.4, … } }

# Approve — video spend starts only now
curl -X POST https://ppl.studio/api/v1/flows/$RUN/approve -H "Authorization: Bearer ppl_live_xxx"

Auth tiers

  • API keyPer-user key (ppl_live_…) — every /api/v1/* route, scoped to your account. A signed-in dashboard session works on the same routes.
  • SessionSigned-in session only — managing API keys and your Gemini key. A key can't mint keys.
  • x-api-keyPartner key — writes to the shared persona directory.
  • PublicNo auth — anonymous, rate-limited free tools.

Response envelope

// /api/v1 success            // failure (4xx / 5xx)
{ "ok": true, "data": … }   { "ok": false, "error": "message" }

Key off the HTTP status: auth failures (401, 403) and rate limits (429) can come back as a bare { "error": "…" }. 404 means missing or not yours — other users' rows are never revealed. Free-tool endpoints return their payload with no envelope.

Plans, limits and 429s

Images spend hosted generation slots unless you've connected your own Gemini key (then they're unlimited). Video — Veo, the voice, lip-sync — needs the Creator plan and your own Gemini key; without them a video step answers 403. Text-model calls (scripts, hooks, captions, topics, persona writing) are capped per user per day only while they run on the platform's key; over the cap is a 429 with Retry-After and X-RateLimit-Policy. GET /api/v1/account tells you where you stand before you call.

Async jobs

Anything slow is a job: the start call answers 202 (or 201) with a jobId, and you poll the matching GET …/{id} until status is done, failed or cancelled. Runs are polled at GET /api/v1/flows/{id}, whose next names the call that moves the run on. videos/assemble and videos/upscale also take an https callbackUrl. GET /api/v1/queue lists everything in flight.

The priced preview

A workflow run writes, voices and frames by itself, then stops at the preview — the frames with the line said over each, priced by the server — until you POST /api/v1/flows/{id}/approve. No video money is spent before that, unless the run was started straightThrough.

Idempotency

POST /api/v1/images/photo-pack and POST /api/v1/images/bulk honour an optional Idempotency-Key header: a retry with the same key and body replays the first answer instead of paying again (24 h). Same key with a different body is a 422; one still in flight is a 409.

Files

Endpoints take hosted URLs. To host a local file, POST /api/v1/uploads (images ≤ 5 MB, video / audio ≤ 9 MB), or upload video and audio up to 512 MB in parts with /api/v1/uploads/multipart. An image elsewhere on the web: the same endpoint with JSON { url } keeps a copy. The URL you get back is public and permanent.

Account & usage

Your plan, your limits and everything in flight. API keys and the Gemini key are managed with a signed-in session, never with a key.

GET/api/v1/accountAPI key

Who you are and what you may generate right now — call it first to explain why an image or video step would be refused.

Response

{ "ok": true, "data": {
  "user": { "id", "email", "name", "image", "createdAt" },
  "authenticatedWith": "api_key | session",
  "plan": "free | creator | studio",
  "gemini": { "connected": true, "imageModel": "string" },
  "fal": { "connected": true },
  "images": { "unlimited", "hostedUsed", "hostedLimit", "hostedRemaining": "number | null", "refusal": "string | null" },
  "video": { "allowed", "denied": "plan | key | null", "reason": "string | null" }
} }
images: with your own Gemini key you're unlimited; without one, images use hosted slots — a lifetime count that never resets. refusal is the error an image request would get now (HOSTED_LIMIT_REACHED on free, the add-your-key message on Creator). video: Veo, the voice and lip-sync need Creator and your own key. fal: songs, MiniMax video, lip-sync and word-timed captions need your own fal.ai key (Account settings). Keys are never returned.
GET/api/v1/queueAPI key

Every generation job of yours, across every job table — what the Queue page lists.

Request

?hours=72        // 0 = all time
&limit=80        // max 200
&status=queued | running | done | failed   // narrows items only

Response

{ "ok": true, "data": {
  "items": [{ "id", "kind": "video | assembly | image | lipsync | clip | upscale | brick",
              "status": "queued | running | done | failed", "rawStatus", "title", "detail", "error",
              "attempts", "createdAt", "startedAt", "finishedAt", "href", "retryHref", "resultUrl",
              "previewUrl", "step": { "brick", "variant" }, "runningMinutes", "stalled" }],
  "counts": { "queued", "running", "done", "failed" }, "inFlight", "failed", "active",
  "window": { "hours", "limit" }
} }
href / retryHref are dashboard paths; a run's detail is GET /api/v1/flows/{id}. Poll while active is true.
GET/api/v1/account/api-keysSession

List your API keys — never the secret.

Response

{ "ok": true, "data": { "keys": [{ "id", "name", "key_prefix", "last_used_at", "revoked_at", "created_at" }] } }
POST/api/v1/account/api-keysSession

Mint a key (201). The raw key is returned once.

Request

{ "name"?: "string (default 'API key')" }

Response

{ "ok": true, "data": { "raw": "ppl_live_…", "row": { "id", "name", "key_prefix", … } } }
GET/api/v1/account/gemini-keySession

Whether you have your own Gemini key saved, and the image model (the same for every account).

Response

{ "ok": true, "data": { "hasKey": true, "imageModel": "string" } }
PUT/api/v1/account/gemini-keySession

Save your own Gemini key — lifts the hosted image cap and the text rate limits; with Creator it unlocks video.

Request

{ "key": "string" }

Response

{ "ok": true, "data": { "saved": true } }

Uploads

Host a local file, or copy an image from a URL, and get back a permanent public URL — for products, personas, the gallery, run inputs, video clips and brick audio.

POST/api/v1/uploadsAPI key

Store one file (201): multipart/form-data — or, for an image on the web, JSON { url }.

file (required): an image — JPEG, PNG, WebP, GIF ≤ 5 MB; a video — MP4, MOV, WebM ≤ 9 MB; or audio — MP3, WAV, M4A ≤ 9 MB. The type comes from the part's Content-Type (or the filename's extension) and must match the bytes. gallery=true also adds an image to your gallery.
JSON { url, gallery? } instead: we download an image from an http(s) link (JPEG, PNG, WebP, GIF ≤ 5 MB, 15 s) and store a copy exactly like an uploaded file, typed by its bytes. gallery: true adds it to your gallery. Links to private, loopback or link-local addresses are refused, on every redirect too (at most 3); a link to a web page rather than the image itself is a 400.

Request

curl -X POST https://ppl.studio/api/v1/uploads \
  -H "x-api-key: ppl_live_xxx" \
  -F file=@serum.jpg -F gallery=true

# an image from a URL
curl -X POST https://ppl.studio/api/v1/uploads \
  -H "x-api-key: ppl_live_xxx" -H "content-type: application/json" \
  -d '{ "url": "https://example.com/serum.jpg", "gallery": true }'

Response

{ "ok": true, "data": {
  "url": "https://…", "kind": "image | video | audio", "contentType", "bytes", "galleryImageId"?
} }
Requests over 10 MB are refused (413) — send larger video or audio in parts, below.
POST/api/v1/uploads/multipartAPI key

Start a large upload — video or audio up to 512 MB, in 8 MB parts (201). Images always use the single upload.

Request

{ "contentType": "video/mp4", "bytes": 214958080 }

Response

{ "ok": true, "data": { "uploadId", "path", "partSize", "maxParts", "kind", "contentType" } }
PUT/api/v1/uploads/multipartAPI key

Upload part N as the raw request body: ?uploadId=&path=&part=N (1-based).

Response

{ "ok": true, "data": { "part": 1, "etag": "string" } }
Every part but the last is exactly partSize bytes. Part 1 is checked against the declared type.
DELETE/api/v1/uploads/multipartAPI key

Abort an upload: ?uploadId=&path=.

Response

{ "ok": true, "data": { "aborted": true } }
POST/api/v1/uploads/multipart/completeAPI key

Finish the upload — every part 1…N once, with the etags PUT returned.

Request

{ "uploadId", "path", "parts": [{ "part": 1, "etag": "…" }, …] }

Response

{ "ok": true, "data": { "url", "kind", "contentType" } }

Projects

Folders for your brands and campaigns. A project holds your experts (persona), props (prop), saved scripts (script) and posting accounts (account); an item can be in several projects at once, and filing it in another adds it there. Anywhere a project id goes, its slug does too.

POST/api/v1/projectsAPI key

Make a project (201). Its slug comes from the name — bae, then bae-2 — and stays when the project is renamed.

Request

{ "name": "Bae", "description"?: "An AI companion app for lonely people" }

Response

{ "ok": true, "data": { "id", "slug", "name", "description", "created_at", "updated_at",
                          "counts": { "persona": 0, "prop": 0, "script": 0, "account": 0 } } }
GET/api/v1/projectsAPI key

Your projects, by name, with how many of each kind each holds.

Response

{ "ok": true, "data": { "projects": [ … ] } }
GET/api/v1/projects/{id}API key

One project (by id or slug) with what's in it, kind by kind.

Response

{ "ok": true, "data": { …project, "items": { "persona": [{ "type", "id", "title", "subtitle", "image", "href" }],
                          "prop": [ … ], "script": [ … ], "account": [ … ] } } }
PATCH/api/v1/projects/{id}API key

Rename it, change its description, or its settings (only the keys sent change). settings.make is what a run of one of its formats starts with — POST /api/v1/flows { format, project } — and what its formats are synced from. settings.make.character (off unless set) makes it a recurring character page: its couple or mascot formats always cast the same mascots, a couple keeps one caption formula, plan/next pins their slots at postAt (set.postAt, an ISO time), and the ladder judges them only after patience posts (30) unless one breaks out.

Request

{ "name"?, "description"?, "settings"?: { "experiments"?, "posts_per_day"?, "paid_budget_usd"?, "lanes"?: { "spark", "screen", "confirm", "run" }, "make"?: { "account", "product", "niche", "subNiche", "niches", "platform", "creator", "cast", "mascots": ["mascot slug"], "styles": { "map"?: "map:swiss", "cartoon"?: "…" }, "app", "prop", "recordings", "character"?: { "kind": "couple | mascot", "slugs": ["mascot slug"], "captionFormula"?: "choice | when | fact | send", "postAt"?: "HH:MM", "tz"?, "patience"?: 30 } } } }

Response

{ "ok": true, "data": { /* the project */ } }
PUT/api/v1/projects/{id}/nicheAPI key

The project's niches: each a category and the niche inside it, 12 at most (settings.make.niches). Its posts take them in turn, one a post: each run of its formats is briefed inside its niche, and its routines ask for topics in it. [] clears them.

Request

{ "niches": [{ "niche": "relationships", "subNiche": "Loneliness" }, { "niche": "relationships", "subNiche": "Dating advice" }] }

Response

{ "ok": true, "data": { /* the project */ } }
PUT/api/v1/projects/{id}/castAPI key

Who's on camera: which of the project's Experts its runs show, in turn (settings.make.cast; settings.make.creator stays one of them). One at least, each already in the project.

Request

{ "onCamera": ["wren", "zora-vane"] }

Response

{ "ok": true, "data": { /* the project */ } }
DELETE/api/v1/projects/{id}API key

Delete a project. What was in it stays — in its other projects, or in none.

Response

{ "ok": true, "data": { "id", "deleted": true, "unfiled": 7 } }
GET/api/v1/projects/{id}/itemsAPI key

What's filed in it — all kinds, or one with ?type=persona | prop | script | account.

Response

{ "ok": true, "data": { "items": [{ "type", "id", "title", "subtitle", "image", "href" }] } }
POST/api/v1/projects/{id}/itemsAPI key

File items (up to 200 at a time). One in other projects stays in them too; added lists the ones that weren't here yet, and ids that aren't your items of that type come back in missing.

Request

{ "type": "persona | prop | script | account", "ids": ["uuid", …] }

Response

{ "ok": true, "data": { "project": { "id", "slug", "name" }, "type", "filed": [ … ], "added": [ … ], "missing": [ … ] } }
DELETE/api/v1/projects/{id}/itemsAPI key

Take items out of this project. The items themselves stay, and stay in their other projects.

Request

{ "type": "persona | prop | script | account", "ids": ["uuid", …] }

Response

{ "ok": true, "data": { "project": { … }, "type", "removed": [ … ], "missing": [ … ] } }
GET/api/v1/projects/{id}/formatsAPI key

What the project's experiments plan from: its formats by key, each naming the catalogue key it's made from.

Response

{ "ok": true, "data": { "project": { "id", "slug" }, "formats": { "<key>": { "name", "catalog": "explainer:map | house:<slug> | talking:*", "paid"?, "priority"?, "off"?, "why"?, "added"?, "how"? } } } }
PATCH/api/v1/projects/{id}/formatsAPI key

Set formats whole by key, or remove one with null. Only the keys sent change. A format names its catalogue key (GET /api/v1/formats); off: true with a why switches it off for good.

Request

{ "<key>": { "catalog": "chat:thread", "priority"?: 1, "off"?: true, "why"? } | null }

Response

{ "ok": true, "data": { "project": { … }, "formats": { … } } }
POST/api/v1/projects/{id}/formats/syncAPI key

Bring the project's formats in step with the catalogue: every format it can make (from its settings.make — a topic, its App, Expert, screen recordings or Prop) joins as a test, the Ideas app's for its niche first, then ones proven elsewhere, then ppl.studio's own; one the catalogue no longer offers is switched off. Your own switches stay. The day's first plan request runs it too. 400 without settings.make.

Request

{ "dryRun"?: true }

Response

{ "ok": true, "data": { "project": { … }, "added": ["chat-thread", …], "changes": ["… switched off", …], "patch": { … }, "formats": 130 } }
PUT/api/v1/project-itemsAPI key

Put one item in exactly these projects (ids or slugs): it joins the ones it isn't in and leaves the rest; [] takes it out of all. The older { projectId } still works as a one-project list (null: none).

Request

{ "type": "persona | prop | script | account", "id": "uuid", "projectIds": ["bae", "uuid", …] }

Response

{ "ok": true, "data": { "type", "id", "projectIds": [ … ], "projects": [{ "id", "slug", "name" }], "added": [ … ], "removed": [ … ] } }

Personas

The creators in your videos. Full CRUD over the ones you own, AI helpers to write them, their images and passport photo — plus the shared public directory.

GET/api/v1/personasAPI key

List your personas.

Response

{ "ok": true, "data": { "personas": [{ "id", "slug", "name", "label", "niche", "gender",
  "tone_of_voice", "accent", "passport_image_url" }] } }
POST/api/v1/personasAPI key

Create a persona you own (201). 409 if the slug is taken.

name is required; slug defaults to one made from it. Profile fields include niche, label, gender, tone_of_voice, accent, voice (its TTS voice), short_bio, peer_archetype, backstory, visual_description, catchphrases[], interests[], outfits_owned[], avoid_phrases[], and character_level (natural | bold | character; null reads as natural, and an update without it keeps the stored value), and being (person | beast: a Beast is a creature made real, as in a live-action film; null reads as person, kept the same way). Unknown keys are a 400. Videos need a passport photo: set one with …/passport or make one with POST /api/v1/images/generate (type: "passport"). full_body_image_url is read-only, set by …/sheet.

Request

{ "name": "Maya", "niche": "skincare", "tone_of_voice": "warm, direct", … }

Response

{ "ok": true, "data": { /* the persona */ } }
GET/api/v1/personas/{slug}API key

One of your personas (404 if not yours).

Response

{ "ok": true, "data": { /* the persona */ } }
PATCH/api/v1/personas/{slug}API key

Update any of the create fields: only the ones you send change, null or "" clears one. 404 if not yours, 409 if a new slug is taken.

Response

{ "ok": true, "data": { /* the persona */ } }
DELETE/api/v1/personas/{slug}API key

Delete one of your personas (its gallery images are unassigned first).

Response

{ "ok": true, "data": { "slug" } }
POST/api/v1/personas/generateAPI key

Write a persona profile with AI from a niche and/or a product. A draft only, unless save is true.

Request

{
  "niche"?: "string (3+ chars)",
  "productUrl"?: "https://…", "productDescription"?: "string",
  "productType"?: "physical | digital | personal_blog | membership | software | service | other",
  "save"?: false
}

Response

{ "ok": true, "data": { "draft": { "name", "label", "niche", "peer_archetype", "short_bio",
  "tone_of_voice", "visual_description", "backstory", "catchphrases": [ … ], … },
  "persona"?: { … } } }   // persona (201) with save: true
429 at the persona-writing limit without your own key; 503 when no Gemini key resolves. A saved draft whose slug is taken is a 409.
POST/api/v1/personas/proposeAPI key

Propose personas you could create next, written from your business, a project, its brand rules, your current personas and what's trending. Nothing is saved.

Request

{
  "steer"?: "string (≤ 400 chars), e.g. older, Spanish-speaking, a skeptic",
  "level"?: "natural | bold | character",   // default natural
  "being"?: "person | beast",                // default person
  "count"?: 4,                               // 1–6
  "project"?: "id or slug",
  "exclude"?: ["names already shown"],
  "image"?: { "data": "base64", "mimeType": "image/png | image/jpeg | image/webp" }
}

Response

{ "ok": true, "data": {
  "proposals": [{ "name", "angle", "why", "voice", "character_level", "being", "based_on", "label", "niche",
    "gender", "date_of_birth", "visual_description", "signature_details": [ … ], "wardrobe_style", … }],
  "basedOn": ["string"],
  "faces": "auto | on-demand" } }
A steer naming a character ("Winnie-the-Pooh if it was a real person") casts takes on that character, and based_on names it; image is a picture of it, read for its traits and never drawn from. A real person is never a character to base on. To create one, drop angle, why and based_on and send the rest to POST /api/v1/personas. Draw its face first with …/propose/portrait and adopt it with …/{slug}/sheet. faces is auto when faces cost you nothing (your own key) and on-demand when each would spend a free photo. 429 at the persona-writing limit without your own key; 503 when no Gemini key resolves; 404 for a project that isn't yours.
POST/api/v1/personas/propose/completeAPI key

Write the rest of a proposal's profile: backstory, catchphrases, interests and the other fields a proposal leaves out.

Request

{
  "proposal": { "name", "angle", "character_level"?, … },   // a proposal from /propose
  "project"?: "id or slug"
}

Response

{ "ok": true, "data": { "proposal": { …the same proposal, "backstory", "catchphrases": [ … ], "interests": [ … ], … } } }
The proposal's own fields are kept as given. One that already has a backstory or catchphrases comes back unchanged. 429 at the persona-writing limit without your own key; 503 when no Gemini key resolves.
POST/api/v1/personas/propose/portraitAPI key

Draw a proposal's face before the persona exists: a passport-style photo at 1K, kept out of your gallery until a persona adopts it.

Request

{ "proposal": { "name", "angle"?, "why"?, "label"?, "gender"?, "date_of_birth"?, "age_range"?,
  "race"?, "visual_description"?, "signature_details"?: [ … ], "wardrobe_style"?, "niche"?,
  "character_level"?, … },   // a proposal from /propose
  "save": true }             // also keep it in the Expert library
// or { "look": { …the same fields, name optional } }  — the face only

Response

{ "ok": true, "data": { "url": "https://…", "libraryId": "uuid | null" } }   // libraryId only with save
Create the persona, then adopt the face with POST /api/v1/personas/{slug}/sheet { passport_url }. With save the proposal is also kept in the Expert library, so a face you don't pick is offered to the next account (libraryId is null when it couldn't be kept; the face still comes back). One image: your own Gemini key, else one of your free photos. 402 when no free photo is left (HOSTED_LIMIT_REACHED on free, the add-your-key message on Creator).
POST/api/v1/personas/{slug}/sheetAPI key

Draw the persona's character sheet: the passport (face on white) and the full body (head to toe on white, drawn from the passport).

Request

{
  "parts"?: ["passport", "full_body"],   // omitted: whatever is missing; []: nothing
  "passport_url"?: "https://… (a face from /propose/portrait, adopted as the passport first)"
}

Response

{ "ok": true, "data": { "passport_image_url", "full_body_image_url" } }
An adopted face is never redrawn. A full body without a passport draws the passport first. Each image uses your own Gemini key, else one of your free photos: 402 when none is left (HOSTED_LIMIT_REACHED on free, the add-your-key message on Creator). 404 if the persona isn't yours; 400 for a passport_url that isn't one of your proposal faces.
POST/api/v1/personas/mascot/mainAPI key

A new mascot's main image, three to choose from: a drawn character for cartoon videos (the third kind of Expert), described in words.

Request

{ "look": "a small sleepy sea otter: a round soft deep-teal body…", "style"?: "cartoon:flat-editorial | cartoon:paper-cut | cartoon:clay-toy", "count"?: 1-3 }

Response

{ "ok": true, "data": { "urls": ["https://…"] } }
1K pictures in your proposals folder, not the gallery. Describe the look, never a name. Your own Gemini key: 402 without one.
POST/api/v1/personas/mascotAPI key

Create the mascot Expert from the main image picked.

Request

{ "name", "look", "personality"?, "style"?, "main": "one of the urls /mascot/main drew", "float"?: true, "glow"?: "#rrggbb" }

Response

{ "ok": true, "data": { "id", "slug" } }  (201)
float: it floats instead of standing (a cloud, a moon); glow: the light it gives off in a room. Then draw its poses with POST /api/v1/personas/{slug}/mascot/poses.
POST/api/v1/personas/{slug}/mascot/posesAPI key

Draw a mascot's pose set in a Style: five sheets of four poses (emotions and actions) cut out, the first with talking and blinking frames — or redraw one pose that drifted.

Request

{ "style": "cartoon:flat-editorial", "sheet": 0-4 }   or   { "style", "pose": "happy" }

Response

{ "ok": true, "data": { "poses": ["neutral", …], "frames": ["talk:neutral", …] } }
The five sheets can be drawn side by side: about $0.70 a set (7 pictures at 2K), a pose $0.07–0.20. Your own Gemini key: 402 without one. Read the set with GET /api/v1/personas/{slug}/mascot; use it in a cartoon explainer with options.mascot.
GET/api/v1/personas/{slug}/mascotAPI key

A mascot's kit: its main image, its look, and its pose set per Style (each pose's transparent PNG, the talk: and blink: frames, the poses still missing).

Response

{ "ok": true, "data": { "look", "main", "style", "sets": { "cartoon:flat-editorial": { "poses": { "neutral": "https://…", "talk:neutral": "https://…" }, "sheets", "drawnAt", "missing": [] } } } }
GET/api/v1/mascots/roomsAPI key

The Background Library: empty drawn rooms per cartoon Style, shared by every account, each with the places a mascot can be put.

Request

?style=cartoon:flat-editorial

Response

{ "ok": true, "data": { "rooms": [{ "room": "bedroom", "label", "image_url", "anchors": [{ "id": "bed1", "kind": "stand | seat | bed | desk", "box": [x, y, w, h], "cover"?: 0.4 }] }] } }
A box is fractions of the picture; its bottom is the surface the mascot rests on; cover is the share of it hidden by what stands in front (a desk's edge, a duvet).
POST/api/v1/personas/{slug}/restyleAPI key

Take the persona to another look level. The same person (gender, age, ethnicity, face) with their hair, signature details and wardrobe rewritten to the level, then the face and full body redrawn.

Request

{ "level": "natural | bold | character" }

Response

{ "ok": true, "data": { "character_level", "passport_image_url", "full_body_image_url" } }
One text call and two images. 429 at the persona-writing limit without your own key; 402 when no free photo is left (HOSTED_LIMIT_REACHED on free, the add-your-key message on Creator); 404 if the persona isn't yours; 503 when no Gemini key resolves.
GET/api/v1/personas/libraryAPI key

The Expert library: Experts anyone can claim for free (proposal faces nobody picked, and those added by the library account).

Request

?being=person|beast             // optional, default person
&level=natural|bold|character      // optional
&q=older skeptic                   // optional, ≤ 200 chars: best match first
&limit=8                           // 1–24
&exclude=<id>,<id>                 // optional, ids already shown

Response

{ "ok": true, "data": { "experts": [{ "id", "name", "label", "peer_archetype", "occupation",
  "niche", "city", "gender", "date_of_birth", "age_range", "character_level", "being",
  "passport_image_url", "short_bio" }] } }
Only Experts with a face. Best match to q first (any word in the name, angle, job, niche, bio, city or gender), newest first among equals. Claim one with POST /api/v1/personas/library/{id}/claim.
GET/api/v1/personas/library/{id}API key

One library Expert, whole — what the editor opens when you pick one: every field, both images, and whether it's only a concept so far.

Response

{ "ok": true, "data": { "id", "data": { "name", "label", …every field },
  "passport_image_url", "full_body_image_url", "character_level", "being", "needs_completion" } }
needs_completion: POST /api/v1/personas/propose/complete writes the rest of the dossier (a claim without fields does it too). 404 when it's gone.
POST/api/v1/personas/library/{id}/sheetAPI key

Draw a library Expert's full body before anyone takes them — kept on the library Expert, so it's drawn once whoever opens them.

Response

{ "ok": true, "data": { "full_body_image_url": "https://…" } }
One image through the gate (your own key, else a free photo: 402 when none is left); the existing one comes back free. 404 when the Expert is gone.
POST/api/v1/personas/library/{id}/claimAPI key

Make a library Expert yours, for free. A proposal moves to your account under a free slug, its dossier completed and its face your passport; a public one (it has a dossier) is copied, as with POST /api/v1/personas/public/{id}/copy, and stays public.

Request

{ "fields": { "name": "…", … } }   // optional: the Expert as you reviewed it (POST /api/v1/personas's shape)

Response

{ "ok": true, "data": { "slug": "…" } }
First come, first served: 404 when the Expert is gone or someone claimed it first. Draw its full body with POST /api/v1/personas/{slug}/sheet. Completing the dossier shares the persona-writing limit: 429 without your own key; 503 when no Gemini key resolves.
GET/api/v1/personas/publicAPI key

The public Experts (the ones on /experts — the Expert library's with a written dossier): anyone can take a copy, free.

Request

?q=skincare for busy moms   // optional, ≤ 400 chars: best match first
&limit=8                       // 1–24

Response

{ "ok": true, "data": { "experts": [{ "id", "name", "label", "niche", "passport_image_url" }] } }
Only Experts with a face. Best match to q first (any word in the name, label, niche, job, angle or bio), then in an order of your own that stays the same between calls. Copy one with POST /api/v1/personas/public/{id}/copy.
POST/api/v1/personas/public/{id}/copyAPI key

Take a copy of a public Expert: a new persona of yours with the whole dossier and the face as its passport. Nothing is generated; the original stays public.

Response

{ "ok": true, "data": { "slug": "…" } }
The copy leaves out the original's contact links, certification and quotes. 404 when the id isn't a public Expert. Draw its full body with POST /api/v1/personas/{slug}/sheet.
POST/api/v1/personas/{slug}/fieldsAPI key

The edit form's AI helpers on a saved persona: fill every empty field, write one, or shrink / enlarge one.

Request

{ "action": "fill_empty", "context"?: { … }, "save"?: false }
{ "action": "generate", "field", "currentValue"?, "context"?, "save"? }
{ "action": "shrink" | "enlarge", "field", "currentValue"?, "save"? }
// field: short_bio | tone_of_voice | accent | visual_description | backstory

Response

{ "ok": true, "data": { "fields": { … } } }            // fill_empty
{ "ok": true, "data": { "field", "content" } }         // generate / shrink / enlarge
// + "persona": { … } when save is true
context is unsaved field values the model reads, never saved themselves. Suggestions only unless save. Same 429 limit as generate.
GET/api/v1/personas/{slug}/imagesAPI key

The persona's UGC images in order, and its passport photo.

Response

{ "ok": true, "data": { "passport_image_url",
  "images": [{ "id", "url", "type", "sort_order", "caption", "generation_params", "created_at", "prompt" }] } }
POST/api/v1/personas/{slug}/imagesAPI key

Add an image to the persona (201): multipart file (JPEG / PNG / WebP / GIF ≤ 5 MB), or JSON { url } to attach a gallery or hosted image.

Response

{ "ok": true, "data": { "url", "image"? } }
DELETE/api/v1/personas/{slug}/imagesAPI key

Unattach an image by URL: ?url=… The image stays in your gallery.

Response

{ "ok": true, "data": { "url", "unattached": true } }
DELETE/api/v1/personas/{slug}/images/{imageId}API key

Unattach an image by id — a no-op if it isn't attached. The image stays in your gallery.

Response

{ "ok": true, "data": { "imageId", "unattached": true } }
PUT/api/v1/personas/{slug}/passportAPI key

Set the passport photo — the reference face for every image and video: multipart file (≤ 5 MB) or JSON { url }.

Response

{ "ok": true, "data": { "url" } }
DELETE/api/v1/personas/{slug}/passportAPI key

Clear the passport photo (the image stays in your gallery).

Response

{ "ok": true, "data": { "passport_image_url": null } }
POST/api/personasx-api-key

Create an unowned persona in the shared directory (partner key).

Same fields as POST /api/v1/personas, plus an optional passport_image_url.

Response

{ "slug": "string", "id": "uuid" }

Products

Your physical products (Props) — what a persona holds, wears or stands beside, the facts the writers use, and what's inside a box or set (the What's-inside carousel). image_urls are hosted URLs (upload first with /api/v1/uploads). App screens are Apps now.

POST/api/v1/propsAPI key

Create a product (201).

Request

{
  "name": "string",
  "category": "handheld | large_object | ambient",
  "text"?: "string (what it is — the writers read it)",
  "image_urls"?: ["https://…"],
  "price"?: 49.99, "currency"?: "USD", "link"?: "https://… (where to buy it)",
  "contents"?: [{ "name", "brand"?, "type"?, "size"?, "imageUrl"?: "https://…", "fullSize"?: true }]   // what's inside, ≤ 60
}

Response

{ "ok": true, "data": { "id", "name", "category", "text", "image_urls", "price", "currency", "link", "contents", … } }
GET/api/v1/propsAPI key

List your products, newest first.

Response

{ "ok": true, "data": { "props": [{ "id", "name", "category", "text", "image_urls", "price", "currency", "link", "contents", "created_at" }] } }
PATCH/api/v1/props/{id}API key

Partial update of name, category, text, image_urls, price (null clears), currency, link, contents (the whole list) — 404 if not yours.

Response

{ "ok": true, "data": { /* the product */ } }
DELETE/api/v1/props/{id}API key

Delete one of your products.

Response

{ "ok": true, "data": { "id", "deleted": true } }

Apps

Your apps — and others' you talk about (own: false): screens and a store listing, for app demos and app carousels. From an App Store link the icon, screens and words come in (copied to your storage); the listing's numbers — rating, price, version, release notes — are read live when a run uses them.

POST/api/v1/appsAPI key

Add an app (201): from its App Store link, or by hand (Google Play, web). The same store app twice is refreshed, not duplicated.

Request

{ "storeUrl": "https://apps.apple.com/us/app/…/id570060128" | "storeId": "570060128", "country"?: "us", "own"?: true }
// or by hand:
{ "name", "platform"?: "ios | android | web", "own"?, "description"?, "iconUrl"?,
  "screenshots"?: [{ "url": "https://…", "device"?: "phone | tablet | desktop", "caption"? }] }

Response

{ "ok": true, "data": { "id", "name", "own", "platform", "store_id", "store_url", "country", "developer",
                          "genre", "description", "icon_url", "screenshots": [{ "url", "device", "caption", "source" }], … } }
GET/api/v1/appsAPI key

Your apps, yours first.

Response

{ "ok": true, "data": { "apps": [ … ] } }
GET/api/v1/apps/{id}API key

One app. ?live=1 adds the App Store's numbers right now (null for apps not on the store).

Response

{ "ok": true, "data": { …app, "listing"?: { "rating", "ratingCount", "priceLabel", "version", "releaseNotes", "phoneScreens", … } } }
PATCH/api/v1/apps/{id}API key

Change name, own, platform, storeUrl, country, developer, genre, description, iconUrl, screenshots (the whole list, in order — reorder, caption, drop or add).

Response

{ "ok": true, "data": { /* the app */ } }
POST/api/v1/apps/{id}/refreshAPI key

Read the store listing again: new screens, icon and words; uploaded screens and captions stay.

Response

{ "ok": true, "data": { /* the app */ } }
DELETE/api/v1/apps/{id}API key

Delete an app. Carousels made from it keep their slides.

Response

{ "ok": true, "data": { "id", "deleted": true } }

Catalogs

Your product feeds — a Google Merchant or Meta feed, a Shopify or WooCommerce shop, or a CSV. Only where the feed is gets saved: the products are read live whenever you look or a run starts, and a carousel keeps just the ones it showed, as they were that day.

POST/api/v1/catalogsAPI key

Save a feed (201). From an address, what it is is worked out; or upload a CSV (multipart, ≤ 8 MB — a Shopify product export reads as is).

Request

{ "url": "https://yourshop.com" | "https://…/feed.xml", "name"?, "currency"?: "USD", "siteUrl"? }
// or multipart/form-data: file (.csv / .tsv), name?, currency?, siteUrl?

Response

{ "ok": true, "data": { "id", "name", "url", "format": "merchant | shopify | woocommerce | csv", "site_url", "currency",
                          "last_read_at", "last_count", "last_error", … } }
GET/api/v1/catalogsAPI key

Your catalogs.

Response

{ "ok": true, "data": { "catalogs": [ … ] } }
GET/api/v1/catalogs/{id}/itemsAPI key

The feed's products, read live (reused 5 minutes; ?fresh=1 reads again). ?q= matches title, brand and labels; ?limit=&offset= page. Feeds past 5,000 products are cut there.

Response

{ "ok": true, "data": { "items": [{ "key", "title", "brand", "subtitle", "price": { "amount", "currency" }, "salePrice",
                                   "images", "link", "availability", "publishedAt", "labels" }],
                          "total", "matched", "readAt", "truncated" } }
POST/api/v1/catalogs/{id}/propsAPI key

Keep one product as a Prop (201) — its name, description, first two photos (copied), price and link.

Request

{ "itemKey": "string (from …/items)" }

Response

{ "ok": true, "data": { /* the Prop */ } }
PATCH/api/v1/catalogs/{id}API key

Change name, currency, siteUrl or format.

Response

{ "ok": true, "data": { /* the catalog */ } }
DELETE/api/v1/catalogs/{id}API key

Forget the feed's address (the feed itself is untouched).

Response

{ "ok": true, "data": { "id", "deleted": true } }

Stock photos

Free photos from Pexels, for carousel covers and backgrounds. Show 'Photos provided by Pexels' and each photographer's name wherever you show results. Licence: commercial use and edits are fine; don't imply the people in a photo endorse your product.

GET/api/v1/stock/photosAPI key

Search: ?q=gift+boxes[&page=1&orientation=portrait | landscape | square]. configured: false when the server has no Pexels key.

Response

{ "ok": true, "data": { "configured": true, "photos": [{ "id", "width", "height", "thumb", "full", "photographer",
                          "photographerUrl", "pageUrl", "alt" }], "total", "attribution": { "text", "url" } } }
POST/api/v1/stock/photosAPI key

Keep one (201): a copy in your storage and gallery — pass its url on (a carousel's options.coverPhoto).

Request

{ "id": 1234567 }

Response

{ "ok": true, "data": { "id", "url", "photographer", "pageUrl" } }

Images

UGC photos, passports, product packs and app screens — made now (synchronous, tens of seconds) or as jobs. Each image spends one hosted slot unless you've connected your own Gemini key; all are saved to your gallery.

GET/api/v1/images/optionsAPI key

The Workbench's scene options — what optionsMap takes in structured mode — plus whole-scene presets, gaze and head angles.

Response

{ "ok": true, "data": {
  "groups":  [{ "id", "label", "section", "multiSelect", "choices": [{ "value", "label" }] }],
  "presets": [{ "id", "label", "description"?, "optionsMap", "clothingText"? }],
  "gaze":    [{ "id", "label", "eyeGazeX", "eyeGazeY" }],
  "head":    [{ "id", "label", "headTiltX", "headTiltY" }],
  "skipValue": "__skip__", "customValue": "__custom__"
} }
POST/api/v1/images/generateAPI key

One UGC photo (or a persona's passport), made now (201).

JSON with hosted image URLs (fileUrl, handheldImageUrls, … ≤ 5 a field) or multipart/form-data with the files themselves. Unknown keys are a 400. A product (handheldPropId etc., from /api/v1/props) brings its text and photos; otherwise describe the object in words and photos. Poses come from /api/v1/visual-presets.

Request

{
  "type"?: "ugc | passport",
  "characterSourceType"?: "persona | upload | custom",
  "personaSlug"?: "string", "saveToPersonaSlug"?: "string",
  "characterDescription"?: "string", "fileUrl"?: "https://… (upload: the person)",
  "personaContext"?: { "niche"?, "interests"?: ["string"], "phone_model"? },
  "promptMode"?: "structured | custom",
  "optionsMap"?: { "<groupId>": "value | [values]", "eyeGazeX"?: 0, "headTiltY"?: 0 },
  "customTextPerGroup"?: { "<groupId>": "text" },
  "customPrompt"?: "string", "fullPromptOverride"?: "string",
  "selectedOutfits"?: ["string"],
  "handheldPropId"? | "handheldText"? + "handheldImageUrls"?: ["https://…"],
  "largeObjectPropId"? | "largeObjectText"? + "largeObjectImageUrls"?,
  "ambientPropId"? | "ambientText"? + "ambientImageUrls"?,
  "referenceText"?, "referenceImageUrls"?, "clothingText"?, "clothingImageUrls"?,
  "visualPresetClothing"?, "visualPresetBackground"?, "usePresetClothing"?, "usePresetBackground"?
}

Response

{ "ok": true, "data": { "imageUrl": "https://…" } }
passport with a personaSlug is saved as that persona's passport photo. Out of hosted slots: HOSTED_LIMIT_REACHED (free) or the add-your-key message (Creator).
POST/api/v1/images/jobsAPI key

Queue one UGC photo instead (202) — exactly the body of /images/generate. Refuses at once on the same limits.

Response

{ "ok": true, "data": { "job": { "id", "status": "queued", "previewUrl", "resultUrl": null, "error": null, "createdAt" } } }
GET/api/v1/images/jobsAPI key

?ids=a,b (up to 100) — those jobs; no ids — your queued and running jobs and those that failed in the last 24 h (≤ 50).

Response

{ "ok": true, "data": { "jobs": [{ "id", "status": "queued | running | done | failed",
  "previewUrl", "resultUrl", "error", "createdAt" }] } }
GET/api/v1/images/jobs/{id}API key

Poll one queued photo. resultUrl is the image once done.

Response

{ "ok": true, "data": { "job": { "id", "status", "previewUrl", "resultUrl", "error", "createdAt" } } }
POST/api/v1/images/jobs/{id}/retryAPI key

Queue a failed photo again as a new job (202; no body). No new slot is spent. 404 unless yours and failed.

Response

{ "ok": true, "data": { "job": { "id": "the new job", … } } }
POST/api/v1/images/bulkAPI key

Several images of a persona from one prompt, rendered in parallel and saved to the persona. Honours Idempotency-Key.

Request

{ "personaSlug": "string", "prompt": "string (the whole scene)", "count"?: 1-10 }   // default 3

Response

{ "ok": true, "data": { "imageUrls": ["string"], "succeeded": 3, "failed": 0, "errors"?: ["string"] } }
Each image spends a slot, so a partial batch is normal — check failed and errors.
POST/api/v1/images/editAPI key

An existing image edited into a new one — Darkroom's tools (201). Saved to the gallery.

Request

{
  "op": "angle",
  "source": "https://…" | { "imageId": "a gallery image of yours" },
  "azimuth": 0-315,     // snapped to 45° steps: 0 front, 90 right, 180 back, 270 left
  "elevation": -30 | 0 | 30 | 60,
  "distance": 0.6 | 1.0 | 1.4,   // close-up, medium, wide
  "personaSlug"?: "string (save to this persona too)"
}

Response

{ "ok": true, "data": { "op": "angle", "imageUrl" } }
expand (another shape) and combine (several images into one) are not built yet: they answer 400 and nothing is spent.
POST/api/v1/images/camera-angleAPI key

The same scene from another camera angle (201) — the same edit as /images/edit with op angle.

Request

{
  "sourceImageUrl": "https://…",
  "azimuth": 0-315,     // snapped to 45° steps: 0 front, 90 right, 180 back, 270 left
  "elevation": -30 | 0 | 30 | 60,
  "distance": 0.6 | 1.0 | 1.4,   // close-up, medium, wide
  "personaSlug"?: "string (save to this persona)"
}

Response

{ "ok": true, "data": { "imageUrl" } }
POST/api/v1/images/expand-storyAPI key

The next image of a story: the same person, the next moment (201). JSON with hosted URLs, or multipart with files.

Request

{
  "currentImageUrl": "https://… (the last image)",
  "whatHappensNext": "string",
  "personaSlug"?: "string", "saveToPersonaSlug"?: "string",
  "handheldPropId"? | "handheldText"? + "handheldImageUrls"?,
  "largeObjectPropId"? | "largeObjectText"? + "largeObjectImageUrls"?,
  "ambientPropId"? | "ambientText"? + "ambientImageUrls"?
}

Response

{ "ok": true, "data": { "imageUrl" } }
GET/api/v1/images/photo-packAPI key

The shot plans — Product UGC, Amazon, Shopify, Before/After — with each shot's role.

Response

{ "ok": true, "data": { "plans": [{ "slug", "title", "productCategory", "aspectRatio",
  "shots": [{ "role", "label", "description", "needsPersona", "referenceRole"? }] }] } }
POST/api/v1/images/photo-packAPI key

Make the asked-for shots of a plan for one of your products, now, in parallel (a minute or more). Honours Idempotency-Key.

Request

{
  "workflowSlug": "string (a plan's slug)",
  "propId": "uuid (your product)",
  "roles": ["string (the plan's shots to make)"],
  "personaSlug"?: "string (for needsPersona shots)",
  "context"?: "direction for every shot",
  "contextByRole"?: { "<role>": "direction" },
  "references"?: { "<role>": "imageUrl (an already-made shot to match)" }
}

Response

{ "ok": true, "data": { "shots": [{ "role", "imageUrl": "string | null", "error": "string | null" }] } }
A partial pack is normal — ask again for the roles that failed. A Before/After "after" remade alone takes its "before" in references.
POST/api/v1/images/product-shotsAPI key

A whole plan's shots as one job (202; 200 when the same job is already running). A failed shot gets one more try.

Request

{ "plan": "string (a plan's slug)", "productId": "uuid", "personaSlug"?: "string", "direction"?: "string" }

Response

{ "ok": true, "data": { "jobId", "existing": false } }
GET/api/v1/images/product-shots/{id}API key

Poll a product-shots job. When done, output.frames are the images in plan order.

Response

{ "ok": true, "data": { "job": {
  "id", "brick": "picture", "variant": "product-shots",
  "status": "queued | running | waiting | done | failed | cancelled",
  "progress": { "stage", "message", "done"?, "total"?, "updatedAt" } | null,
  "output": { "frames": [{ "id", "kind": "image", "url", "use": { "segmentRole", … } }],
              "missing": [{ "role", "label", "error" }] },
  "error", "createdAt", "finishedAt"
} } }
POST/api/v1/images/app-screenAPI key

The persona holding a phone (or beside a laptop) with your app's screenshot on it, as a job (202).

Request

{
  "personaSlug": "string",
  "appId"?: "uuid (one of your /api/v1/apps)", "screen"?: 0 (which of its screens) | "screenUrl"?: "https://… (a hosted screenshot)",
  "appName"?: "string", "device"?: "mobile | desktop",
  "line"?: "≤ 180 chars — what they'll say, kept for animating"
}

Response

{ "ok": true, "data": { "jobId", "existing": false } }
GET/api/v1/images/app-screen/{id}API key

Poll an app-screen job. When done, output.frames[0].url is the image.

Response

{ "ok": true, "data": { "job": { "id", "status", "progress",
  "output": { "frames": [{ "id", "kind": "image", "url", "use": { "line", "prompt", "seconds" } }] },
  "error", "createdAt", "finishedAt" } } }
POST/api/v1/images/burn-captionAPI key

Burn a TikTok-style caption into an image. Admin only (403 otherwise). Nothing is saved.

Request

{ "imageUrl": "https://…", "text": "string" }   // or multipart { image: File, text }

Response

{ "ok": true, "data": { "mimeType", "filename", "base64" } }

Writing

The Script engine: every writer in the app. Pass a brief and the copy is written to its goal, platform, product facts and audience, then checked — banned register, the close the platform allows, line length, a headline figure no line says — with one targeted repair.

POST/api/v1/topicsAPI key

Topic ideas a creator is credible posting — for a carousel, a short-form video or a talking-head clip — each with a TikTok search phrase to study what already wins.

personaSlug shapes the ideas to the creator; nicheCategory (and a subNiche inside it) keeps every idea in that niche; seed is your own idea to develop. A goal and a saved productId set the product up without naming it. With a niche (picked, else the account's, else read from the creator) up to eight of its trending topics (GET /api/v1/trends) reach the writer — trending: mix (default) uses one where it fits, prefer makes at least half the ideas from them, off leaves them out — and an idea on one carries trend.

Request

{
  "medium"?: "carousel | video | talking",
  "personaSlug"?: "string (yours)",
  "nicheCategory"?: "beauty-skincare | fitness | travel | … (the niche playbooks)",
  "subNiche"?: "string", "seed"?: "string",
  "focus"?: "free-text subject; overrides nicheCategory/subNiche",
  "goal"?: "reach | saves | comments | follows | clicks | sales",
  "platform"?: "tiktok | reels | shorts | meta-paid | tiktok-paid",
  "audience"?: "string", "product"?: "string", "productId"?: "uuid",
  "language"?: "string", "count"?: 3-12,
  "trending"?: "mix | prefer | off",
  "accountId"?: "uuid (a posting account: its brand rules shape the ideas; one with a never-say phrase is dropped)",
  "theme"?: "string (an experiment slot's set.theme: every idea is about it)",
  "angle"?: "string (an experiment slot's set.angle: every idea is told from it)"
}

Response

{ "ok": true, "data": { "topics": [{ "title", "angle", "searchQuery"?, "trend"?: { "source": "tiktok | search", "why" } }] } }
GET/api/v1/hooksAPI key

The hooks that worked in a niche — how posts that beat their creator's usual views opened, as recipes to open a run on or to test against each other.

From the same library (the Hooks tab on /topics), best evidence first: multiple is the post's views over the creator's usual. preset puts the hooks that workflow makes first. Open a run on one with POST /api/v1/flows and options: { opening: recipe }; test two or three with POST /api/v1/hook-tests. Without a niche: every niche's counts and its top three. Writers are offered their niche's hooks by themselves when a run has no opening.

Request

?niche=relationships&preset=text-message-video&limit=30   // limit 1-30 (30)

Response

{ "ok": true, "data": { "generatedAt", "niche", "counts": { "hooks", "posts" },
  "hooks": [{ "recipe": "if your situationship does [this], it's over", "onScreen", "spoken", "family", "structure",
              "preset", "recipeKey", "medium", "formatSlug", "multiple", "posts", "via": "post | format",
              "whatToSteal", "whatNotToCopy", "example": { "url", "platform", "creator", "handle", "postedAt" } | null }] } }
// no niche → { "generatedAt", "niches": [{ "niche", "hooks", "posts", "top": [ …three hooks ] }] }
POST/api/v1/scripts/generateAPI key

Talking-head scripts: one candidate per viral structure (three by default).

format is a video format (talking-5, full-viral, story-pov…). With a brief, structures are picked for its goal (and from your recorded outcomes); mode: "exploit" repeats one structure so candidates differ by hook. workflowSlug sets the angle (creator or testimonial). Save one with POST /api/v1/saved-scripts and shoot it with …/send.

Request

{
  "niche": "string",
  "format": "talking-5 | full-viral | story-pov | …",
  "personaSlug"?: "string (yours)",
  "variations"?: 2-6,
  "workflowSlug"?: "creator-ugc-video | testimonial-video | …",
  "brief"?: {
    "goal": "reach | saves | comments | follows | clicks | sales",
    "platform": "tiktok | reels | shorts | meta-paid | tiktok-paid",
    "niche"?: "what it's about", "nicheCategory"?: "a niche playbook id", "subNiche"?: "string",
    "product"?: "string",
    "productId"?: "uuid (one of your /api/v1/props — its facts reach the writer)",
    "audience"?: "string", "language"?: "string"
  },
  "mode"?: "explore | exploit", "exploitStructure"?: "string"
}

Response

{ "ok": true, "data": {
  "scripts": [{ "structureType", "family", "hookText", "claimLimit", "productEntrySegment", "whyItWorks",
                "segments": [{ "segmentRole", "spokenLine", "onScreenText", "visualDirection" }] }],
  "structures": [ … ],
  "brief"?: { … }
} }
POST/api/v1/scripts/hooksAPI key

Alternative openings for a script whose body stays fixed — the cheapest lever once a script exists.

Request

{ "script": { "structureType", "hookText", "segments": [ … ] }, "brief": { … },
  "count"?: 5, "personaName"?: "string", "toneOfVoice"?: "string" }

Response

{ "ok": true, "data": { "variants": [{ "hookText", "spokenLine", "family", "note" }] } }
POST/api/v1/scripts/critiqueAPI key

Score one talking-head script before anything is rendered, with a rewrite of its weakest segment.

Request

{
  "niche", "format", "hookText",
  "segments": [{ "segmentRole", "spokenLine", "onScreenText" }],
  "brief"?: { … }, "structureType"?: "string", "claimLimit"?: "string"
}

Response

{ "ok": true, "data": { "critique": {
  "score", "verdict", "strengths": [ … ], "issues": [ … ], "weakestIndex", "weakestRewrite",
  "dimensions"?, "sendTarget"?, "leavePoints"?, "productEntrySegment"?, "bannedClaims"?, "fix"?, "seed"?
} } }
With a brief the rubric is goal-weighted and score is the weighted composite of dimensions.
POST/api/v1/scripts/rankAPI key

Rank up to 8 candidate scripts side by side in one comparative call (scoring each alone bunches the results).

Request

{ "niche", "format", "candidates": [{ "structureType"?, "hookText", "segments": [ … ] }] }

Response

{ "ok": true, "data": { "ranking": { "order": [2, 0, 1], "entries": [{ "index", "rank", "score", "verdict" }] } } }
POST/api/v1/scripts/reviseAPI key

Apply a plain-English change to a script (“make it shorter”), then the shared copy check.

Request

{ "instruction": "string", "hookText", "segments": [ … ], "niche"?, "personaName"?, "toneOfVoice"?, "brief"?: { … } }

Response

{ "ok": true, "data": { "script": { "hookText", "segments": [ … ], "note"? } } }
With a brief the edit keeps its account's brand rules and its platform's close; an invalid brief is a 400.
POST/api/v1/scripts/translateAPI key

Re-deliver a script for another platform — same idea, the hook rebalanced, the close obeying the new surface. Not a language translation (that's localize).

Request

{ "script": { … }, "brief": { … }, "toPlatform": "tiktok | reels | shorts | meta-paid | tiktok-paid" }

Response

{ "ok": true, "data": { "translation": { "hookText", "hookSecondLine"?, "segments": [ … ], "changes": [ … ] }, "toPlatform" } }
POST/api/v1/scripts/localizeAPI key

A script, slide set or caption in another language — same structure, figures in digits, the product name verbatim.

Request

{ "script": { … }, "format": "talking-5 | …", "language": "Spanish", "product"?: "string" }
// or any copy:
{ "texts": ["string"], "language": "string", "product"?: "string", "medium"?: "carousel slides" }

Response

{ "ok": true, "data": {
  "script" | "texts": …,
  "unresolved": [{ "index", "missingNumbers": ["60"], "productDropped": false }]
} }
POST/api/v1/scripts/long-formAPI key

A one-to-four-minute monologue for one voice — the lip-sync video's script — capped at the render's 620 words.

Request

{
  "seconds": 60 | 120 | 180 | 240,
  "personaSlug"?: "string (yours — its tone of voice)",
  "brief": {
    "goal": "reach | saves | comments | follows | clicks | sales",
    "platform": "tiktok | reels | shorts | meta-paid | tiktok-paid",
    "niche"?: "what it's about", "nicheCategory"?: "a niche playbook id", "subNiche"?: "string",
    "product"?: "string",
    "productId"?: "uuid (one of your /api/v1/props — its facts reach the writer)",
    "audience"?: "string", "language"?: "string"
  },
  "productId"?: "uuid"
}

Response

{ "ok": true, "data": { "title", "paragraphs": ["string"], "script": "string", "words": 0, "brief": { … } } }
POST/api/v1/scripts/ad-hooksAPI key

Ad hooks by angle — Problem, Curiosity, Social Proof, POV, Bold Claim — each with its spoken line, overlay and opening shot.

Request

{
  "product": "string", "audience"?: "string", "tone"?: "string", "perAngle"?: 1-8,
  "brief"?: {
    "goal": "reach | saves | comments | follows | clicks | sales",
    "platform": "tiktok | reels | shorts | meta-paid | tiktok-paid",
    "niche"?: "what it's about", "nicheCategory"?: "a niche playbook id", "subNiche"?: "string",
    "product"?: "string",
    "productId"?: "uuid (one of your /api/v1/props — its facts reach the writer)",
    "audience"?: "string", "language"?: "string"
  },
  "productId"?: "uuid"
}

Response

{ "ok": true, "data": { "hooks": [{ "angle", "hookText", "onScreenText", "openingVisual" }], "brief"?: { … } } }
POST/api/v1/scripts/ad-scriptAPI key

A 30- or 60-second UGC ad in timed scenes (hook → problem → demo → proof → CTA), opening on a chosen hook.

Request

{
  "product": "string", "audience"?: "string",
  "angle": "Problem-Solution | Transformation | Founder Story | Comparison | Unboxing/Demo",
  "length": "30s | 60s",
  "platform": "TikTok | Instagram Reels | YouTube Shorts | Meta Feed",
  "hook"?: "string — scene 1 says it word for word",
  "brief"?: {
    "goal": "reach | saves | comments | follows | clicks | sales",
    "platform": "tiktok | reels | shorts | meta-paid | tiktok-paid",
    "niche"?: "what it's about", "nicheCategory"?: "a niche playbook id", "subNiche"?: "string",
    "product"?: "string",
    "productId"?: "uuid (one of your /api/v1/props — its facts reach the writer)",
    "audience"?: "string", "language"?: "string"
  },
  "productId"?: "uuid"
}

Response

{ "ok": true, "data": {
  "title", "totalDuration",
  "scenes": [{ "timestamp", "section", "narration", "onScreenText", "shotDescription", "bRoll" }],
  "hook", "beats": [ … ], "cta"?, "brief"?
} }
POST/api/v1/scripts/captionAPI key

The post caption — text, hashtags, an AI disclosure line and a pinned reply — for a script, or for any finished video in your gallery.

Request

{ "asset": { "source": "mascot_videos | videos", "id": "uuid (yours)" },
  "platform"?: "instagram | facebook | tiktok | youtube",
  "accountId"?: "uuid — the posting account whose brand rules it keeps" }
// or a studio script:
{ "script": { … }, "brief": { … }, "personaName"?: "string" }

Response

{ "ok": true, "data": {
  "caption": { "text", "hashtags": ["string"], "disclosure", "pinnedReply"? },
  "provenance"?: { … }
} }
POST/api/v1/scripts/postAPI key

A text post, or a thread, for X, Bluesky or LinkedIn — from a brief, from what a video or slide post says, or from a text (an article, notes) turned into a post. Each post is held to its platform's length; the link is placed by its rule.

Request

{ "surface": "x | bluesky | linkedin",
  "brief"?: { … },                       // required when nothing else is given
  "from"?: { "text": "string" }
        | { "said": { "hook"?: "string", "lines": ["string"] }, "media"?: "video | slides" },
  "thread"?: 1-8,                         // X and Bluesky; LinkedIn is one post
  "link"?: "https://…",
  "personaName"?: "string" }

Response

{ "ok": true, "data": { "post": { "surface", "posts": ["string"], "reply": "string | null" } } }
X counts a link as 23 characters and an emoji as two (280 a post); Bluesky 300 graphemes; LinkedIn 3,000, the first 140 before “…see more”. The link goes in the first reply on X and LinkedIn, under the post on Bluesky. Same daily limit as the caption writer (429).
POST/api/v1/phrasesAPI key

The spoken line for an animated clip, in one of your personas' voices: five variants, or one.

Request

{
  "personaSlug": "string",
  "count"?: 1 | 5,
  "structureTypes"?: ["Micro-Reveal Hook", …],   // at most two for five variants
  "preset"?: { "label", "actionDescription" }     // the action the line should suit
}

Response

{ "ok": true, "data": { "phrases": [{ "phrase", "structureType" }] } }
GET/api/v1/scripts/vaultAPI key

Your language vault — buyer phrases mined from reviews and comments, which the writers pull hooks from. ?nicheCategory=&product=

Response

{ "ok": true, "data": { "entries": [{ "id", "product", "niche_category", "phrase", "theme", "emotion",
  "source", "rating", "status": "candidate | testing | purchased", "occurrences", "created_at" }] } }
POST/api/v1/scripts/vaultAPI key

Mine a paste of reviews or comments (40–40,000 chars) into verbatim phrases, and keep them unless save is false.

Request

{ "text": "string", "kind"?: "reviews | comments", "product"?: "string", "nicheCategory"?: "string", "save"?: true }

Response

{ "ok": true, "data": { "entries": [{ "phrase", "theme", "emotion", "rating", "occurrences" }], "saved", "nicheCategory" } }
DELETE/api/v1/scripts/vaultAPI key

Delete a phrase: body { id } or ?id=.

Response

{ "ok": true, "data": { "id" } }
POST/api/v1/chat/transcribeAPI key

Copy a viral chat: a text-message video's thread (or a photo post's slides) read back line for line — every bubble once, verbatim, who sent it, and the hook laid over it — to redraw with our own Messages screen.

Request

{ "video": "https://… (MP4, MOV or WebM, ≤ 5 min, ≤ 200 MB)" }
// or { "images": ["https://…", …] }   // a photo post's slides, in order, 1–20

Response

{ "ok": true, "data": { "copyable": true,
  "thread": { "hook": "… (\"\" when none)", "timestamp"?, "contact"?, "messages": [{ "from": "me | them", "text" }] },
  "theme": "dark | light", "dropped": ["a photo after 'look at this'"], "seconds"?: 12.4 } }
// or { "ok": true, "data": { "copyable": false, "why": "the punchline is a picture" } }
A video is read from stills about a second apart (at most 40); one vision call, nothing stored. What can't be redrawn (a photo, a voice note, a reaction) is left out and listed in dropped; when the thread's point is one, or it isn't a two-person chat, it isn't copyable. Start the video with POST /api/v1/flows { "preset": "text-message-video", "script": { "kind": "chat", "thread", "copiedFrom"?, "dropped"? }, "options": { "chatTheme": theme } }: no writer, every message kept. Rate limit scripts-analyze (429); 422 when the file can't be fetched or read.

Carousels & story ads

The writers behind the viral-tiktok-carousel and animated-story-ad workflows, callable on their own.

POST/api/v1/carousel/hooksAPI key

Cover hooks for a photo carousel across angles, scored best first. The picked one locks slide 1 of a run (options.lockedCover).

Request

{
  "topic": "string", "formatId"?, "audience"?, "productName"?, "personaName"?, "count"?, "language"?,
  "avoid"?: ["hooks already used"], "reference"?: { /* a format from /carousel/autopsy */ },
  "brief"?: { … }, "productId"?: "uuid"
}

Response

{ "ok": true, "data": { "hooks": [{ "text", "angle", "score", "rationale" }] } }
POST/api/v1/carousel/autopsyAPI key

Clone a winning format: paste a winning slideshow's text (one line per slide) and get its DNA back — the carousel case of POST /api/v1/formats/references.

Request

{ "reference": "slide 1\nslide 2\n…", "topic"?, "productName"?, "language"? }

Response

{ "ok": true, "data": { "format": { "hookShape", "slideCount", "structure", "saveTrigger",
  "productSlot", "proof"?, "visualSwitch"?, "commentTrigger"? }, "referenceId" } }
Hand format to /carousel/hooks as reference, and to a run as options.reference with options.slideCount. It's kept in your reference formats (GET /api/v1/formats) under referenceId; the same pasted text twice is one entry.
POST/api/v1/story-ad/hooksAPI key

Alternative openings for an animated-story-ad script — each a full replacement for scene 1. Feed one to POST /api/v1/flows/{id}/variant.

Request

{ "script": { /* ≥ 2 scenes */ }, "count"?: 3-10, "brief"?, "productName"?, "productId"? }

Response

{ "ok": true, "data": { "hooks": [{ "narration", "action", "visual", "angle", "colorState", "stake" }] } }
POST/api/v1/story-ad/critiqueAPI key

Score a story-ad script against the format's rules before the preview spends narration, image and Veo credits.

Request

{ "script": { "premise", "character", "scenes": [{ "role", "narration", "action", "visual", "shot",
  "angle", "colorState", "transitionOut", "showsProduct", … }] } }

Response

{ "ok": true, "data": { "score", "verdict", "strengths": [ … ], "issues": [ … ], "weakestIndex",
  "weakestRewrite": { "narration", "action" } | null } }

Briefs & saved scripts

A brief says what a piece is for, who it's for and what it sells — saved once, picked by every workflow. Saved scripts are your own library: edit, shoot, and record how each did once posted.

POST/api/v1/briefs/generateAPI key

A brief from a product link or a one-line description: the product, the audience, a creator recommendation (with your best-matching persona), a format and a per-segment script.

Request

{ "mode": "url" | "description", "value": "string (url ≥ 8 chars, description ≥ 12, ≤ 4000)" }

Response

{ "ok": true, "data": { "brief": { "input", "product", "persona": { "recommendation", "resolved" },
  "format", "script", "structureType"?, "scriptBrief"?, "scene", "generatedAt" } } }
502 when the page can't be read or the model fails. Save its fields with POST /api/v1/briefs.
GET/api/v1/briefsAPI key

Your saved briefs, newest first (at most 100).

Response

{ "ok": true, "data": { "briefs": [{ "id", "title", "draft", "createdAt", "source" }] } }
POST/api/v1/briefsAPI key

Save a brief (201). A niche or a product is required. Pass its id as briefId to POST /api/v1/flows.

Request

{
  "draft": { "goal"?: "reach (default) | saves | comments | follows | clicks | sales",
             "platform"?: "tiktok (default) | reels | shorts | meta-paid | tiktok-paid",
             "niche"?, "nicheOverride"?, "subNiche"?, "product"?, "productId"?, "audience"?, "language"? },
  "title"?: "string (defaults to the product, else the niche)"
}

Response

{ "ok": true, "data": { "id", "title", "draft", "createdAt", "source" } }
GET/api/v1/briefs/{id}API key

One saved brief.

Response

{ "ok": true, "data": { "id", "title", "draft", "createdAt", "source" } }
DELETE/api/v1/briefs/{id}API key

Delete a saved brief.

Response

{ "ok": true, "data": { "id" } }
GET/api/v1/saved-scriptsAPI key

Your scripts library, newest-updated first (at most 200). A script sent to a workflow reads its status from the run.

Response

{ "ok": true, "data": { "scripts": [{ "id", "title", "brief", "format", "structure_type", "family",
  "status": "draft | queued | rendering | done | failed", "persona_slug", "run_id", "video_url",
  "created_at", "updated_at", "hookText", "score" }] } }
POST/api/v1/saved-scriptsAPI key

Save a script (201). brief and script are what POST /api/v1/scripts/generate returns; the segment count must match the brief's format.

Request

{ "brief": { … }, "script": { … }, "title"?, "personaSlug"?, "hookVariants"?, "candidates"?, "critique"?, "caption"? }

Response

{ "ok": true, "data": { /* the saved script, as GET /{id} */ } }
GET/api/v1/saved-scripts/{id}API key

One saved script. A script in a run has its status (and video_url once cut) refreshed from the run.

Response

{ "ok": true, "data": { "id", "title", "brief", "format", "structure_type", "family", "script",
  "hook_variants", "candidates", "critique", "caption", "status", "persona_id", "persona_slug",
  "workflow_slug", "run_id", "video_job_id", "video_url", "created_at", "updated_at" } }
PATCH/api/v1/saved-scripts/{id}API key

Edit a draft or failed script. Changing the brief's format needs a script with the matching segment count.

Request

{ "title"?, "personaSlug"?, "brief"?, "script"?, "hookVariants"?, "candidates"?, "critique"?, "caption"? }

Response

{ "ok": true, "data": { /* the updated script */ } }
DELETE/api/v1/saved-scripts/{id}API key

Delete a saved script (a run it was sent to keeps going).

Response

{ "ok": true, "data": { "id" } }
POST/api/v1/saved-scripts/{id}/sendAPI key

Shoot a saved script: starts a run of its video workflow with the script already written (201). It stops at the priced preview like every run.

Request

{
  "personaSlug"?: "string (required when the script has none)",
  "workflowSlug"?: "creator-ugc-video (default) | testimonial-video | …",
  "burnCaptions"?: false, "sameFrame"?: true, "anchorImageUrl"?: "https://…"
}

Response

{ "ok": true, "data": { "runId" } }
The workflow's angle must match the script's. 400 when it's already in a run.
GET/api/v1/saved-scripts/{id}/shoot-briefAPI key

The script as a markdown brief a human creator can film from: the hook word for word, timings, pacing, the product moment.

Response

{ "ok": true, "data": { "markdown", "filename" } }
GET/api/v1/saved-scripts/{id}/outcomesAPI key

What the script did once posted, newest first.

Response

{ "ok": true, "data": { "outcomes": [{ "id", "platform", "window_label", "posted_at", "goal",
  "structure_type", "hook_family", "metrics", "note", … }] } }
POST/api/v1/saved-scripts/{id}/outcomesAPI key

Record the posted numbers (201). They feed the writer: structures that beat your median get picked more.

Request

{
  "metrics": { "views"?, "reach"?, "likes"?, "comments"?, "shares"?, "saves"?, "follows"?,
               "avgWatchPct"?: 0-100, "clicks"?, "purchases"? },   // at least one
  "window"?: "24h | 7d | adhoc", "platform"?: "string", "postedAt"?: "ISO",
  "skepticismComments"?, "intentComments"?, "note"?
}

Response

{ "ok": true, "data": { /* the outcome */ } }
Re-recording a window replaces it. Purchases promote the vault phrases the script spoke.
GET/api/v1/saved-scripts/outcomes/summaryAPI key

What has worked for you for one goal — medians and hit rates per structure. ?goal= (required) &nicheCategory=

Response

{ "ok": true, "data": { "n", "scope": "niche | all-niches", "cohortMedian", "metric",
  "structures": [{ "structureType", "n", "median", "hitRate", "reliableMedian",
                   "status": "reference | trial | supported", "decay"? }],
  "exploitStructure", "skepticismRate" } }

Libraries

The shared, curated libraries: the formats library (the market's formats we can make, and your own), script examples (the structures storyboards start from), poses (a picture's framing, light and pose for image generation to follow) and the format vocabulary. Reads are open to every key; writes are admin only.

GET/api/v1/formatsAPI key

The formats library: the best of the Ideas app's library that ppl.studio can make (house formats: proven formats and strong candidates, carousels and videos) with the market's posts behind them, your own formats (winners you cloned), and the catalogue: every format ppl.studio can make or has from Ideas, in one list, most confident first, tagged. ?niche=&preset= narrow the house formats to what a run could follow; ?niche=&productType=&tag=&origin=&preset=&minConfidence=&price= filter the catalogue (price: free | under-050 | 050-2 | 2-up). Each entry's cost is what one run typically costs in AI calls on your own keys: the median of its workflow's finished runs over 30 days, or an estimate (estimate: true) under 5 runs.

Response

{ "ok": true, "data": {
  "house": { "generatedAt", "ideasRefreshedAt", "formats": [{ "key": "house:<slug>", "slug", "name", "summary", "medium", "recipeKey",
             "preset", "options", "readiness": "ready | close", "status": "proven | candidate | fading", "tier": "proven | strong",
             "freshness", "why", "creators", "bestMultiple", "viralCreators", "seriesCreators",
             "engagement": { "savesPerLike", "sharesPerLike", "commentsPerLike" }, "newestViralPost", "niches", "hookFamily",
             "hookRecipes", "beats", "whatToSteal", "whatNotToCopy", "audience",
             "examples": [{ "creator", "handle", "multiple", "views", "usualViews", "followers", "likes", "saves", "shares",
                            "comments", "sound", "photo", "slides", "hook", "hookRecipe", "url", "postedAt" }],
             "ours": null /* deprecated */ }] },
  "references": [{ "id", "source": "autopsy", "source_url", "name", "kind": "carousel | talking | chat | story | monologue | demo",
                   "preset", "medium", "recipe_key", "niche_categories", "format", "created_at" }],
  "catalog": [{ "key": "house:<slug> | chat:thread | deck:inside | ref:<id> …", "name", "summary", "origin": "ideas | ppl.studio | own",
                "tags": ["proven | strong | candidate | fading", "new", "proven-for-us | weak-for-us", "ideas | ppl.studio | own"],
                "tier", "niches", "productType": "none | app | prop | catalog | creator | recording", "paid", "medium",
                "preset", "presets", "recipeKey", "options", "body", "example": { "hook", "url", "note" } | null, "firstSeen",
                "href", "ours": { "posts", "multiple", "days" } | null, "cost": { "usd", "runs", "estimate" } | null,
                "confidence": { "score": 0-100, "level": "high | medium | low", "why", "own": { "hits", "posts" } | null },
                "ideasOurs": null /* deprecated */ }] } }
Proven: viral — 5× the creator's usual views — for 3 creators, or for one running it as a series; strong: still ranking, and viral for 2 creators or with one 10× breakout. A run left to auto follows one that fits its workflow and niche, taking turns per options.account; ppl.studio's own formats are only the marked fallback. Start one on purpose with POST /api/v1/flows and options.houseFormat: "house:<slug>" — the writer follows its hook recipes, beats, structure, length, best example and never-copy rules (a key the library no longer holds is refused with a 400, never swapped for another pick); from one of your own with options.reference = its format, on its preset. An example is the market's post as facts and its address (TikTok or YouTube) — its pictures stay the creator's. The catalog holds every format once: the Ideas app's at every tier (candidates and fading ones too; any can be named, only proven and strong are followed on auto), ppl.studio's own (chat shapes, carousel formats, data-deck recipes, talking structures, story, lip-sync, demos) and yours. Each says the niches it suits (none: any), what it's made from (productType), whether its video is paid, and how to start it (options, and a whole POST /api/v1/flows body). New: first seen in the last 14 days. Proven for us: its posts on your accounts got 2× the account's usual views or more over 4 posts on 3 days; weak for us: 0.5× or less over 6 posts — from ppl.studio's ledger (ours), unless an account's experiment ladder says first (a champion is proven for us, a resting format weak). A run left to auto skips a format weak for us on its account while another fits. tag takes several (tag=proven,new): an entry carries all of them. confidence (every entry): 0–100, how likely its posts break out — 2× the account's usual views — more often than your other formats'. It starts from the market (Ideas' tier; a ppl.studio shape takes the best tier of the Ideas formats built on it, at half the weight) and your posts of the last 21 days take over; high at 70 and up, low under 40, and why says what it stands on. The catalogue comes in its order. Deprecated, always null for one more release: a house format's ours and an entry's ideasOurs.
POST/api/v1/formats/referencesAPI key

Clone a winning format of any kind: paste a winner's words and get its DNA back, kept in your formats.

Request

{ "kind"?: "carousel | talking | chat | story | monologue | demo", "text": "the winner's words",
  "topic"?, "productName"?, "language"?, "sourceUrl"? }

Response

{ "ok": true, "data": { "kind", "format": { "structure", "hookShape"?, "proof"?, "visualSwitch"?, "saveTrigger"?,
  "commentTrigger"?, "productSlot"?, "length"?, "avoid"?, "slideCount"? }, "referenceId", "reference": { "id", "name", "kind", "preset", … } } }
Paste a carousel's slide text, a talking-head video's transcript and on-screen text, a chat's hook and messages, a story's narration or a demo's lines (up to 8,000 characters; split several winners with a line of --- and what repeats is kept). Follow it with POST /api/v1/flows on reference.preset and options.reference = its format (a carousel also options.slideCount). The same text twice is one entry. Rate limit: scripts-analyze.
DELETE/api/v1/formats/references/{id}API key

Retire one of your reference formats — it leaves the library; runs that followed it keep their copy.

Response

{ "ok": true, "data": { "retired": true } }
GET/api/v1/formats/vocabAPI key

The format vocabulary: every recipe ppl.studio makes, with the run option that selects it, plus the media, structures, hook families and niches formats are labelled in. Keys are stable.

Response

{ "ok": true, "data": { "version", "media", "presets", "talkingFormats", "structures", "carouselFormats", "chatFormats",
                          "deckRecipes", "hookFamilies", "niches",
                          "recipes": [{ "key": "chat:thread", "family", "id", "label", "medium", "presets",
                                        "option": { "key", "value" }, "hookFamily", "signal", "status": "live | demoted" }] } }
Also public, without a key, at /formats-vocab.json.
GET/api/v1/formats/{key}/scriptAPI key

Write a format's script yourself: what it takes. explainer:answer, explainer:chart, explainer:map, the chats (chat:<id>) and the carousels (carousel:<id>) take one (a chart or map film: no shape, its facts with options.factsOnly, a chart or map Style). ?shape= (an answer film: what-is by default, or how-to, how-it-works, vs, worth-it, alternatives, does-it-work, price, facts, for-who) &question= (the question as searched, quoted in the rules) &style= (an answer Style; answer:dot-matrix by default).

Response

{ "ok": true, "data": { "format": "explainer:answer", "preset": "answer-explainer", "mode": "answer", "shape", "shapes", "question",
  "schema": { /* the plan's JSON Schema (draft 2020-12) */ },
  "rules": "the writer's own rules for this shape and question, word for word",
  "checks": ["schema: …", "figures: …", "pace: …", …],
  "timing": { "voice": "Charon", "voiceStyle", "wordsPerSecond": 2.2, "maxShotSeconds": 3.3, "words": [90, 120], "wordsSlack": 10,
              "shots": [14, 22], "scenes": [5, 5], "sceneOrder": [ … ], "seconds": [30, 50], "firstLineMaxWords": 14,
              "laterLineMaxWords": 7, "shotMaxElements": 3, "firstShotMaxElements": 2, "sizes": ["9:16", "16:9"] },
  "style": { "key", "name", "note", "signature", "banned", "codeChecks", "captions" }, "styles": [{ "key", "name", "note" }],
  "elements": [{ "type": "caption3 | headline | counter | bars | line | icon | chip | arrow", "renders", "limits" }],
  "facts": { "required": true, "min": 2, "format": "- <claim> (<source title>, <date>)", "where": "options.facts" },
  "example": { "options": { "shape", "question", "facts", "style" }, "script": { "kind": "explainer", "plan": { … } } },
  "send": { "start", "check", "refused" } } }
For a caller with its own model and research (a routine): it writes the plan, ppl.studio voices and draws it. rules is the text the built-in writer is given after its inputs (its prompt adds the brief's preamble, the question and the facts), from the same source, so the two never drift. Send the plan as script: { "kind": "explainer", "plan" } on POST /api/v1/flows with format: "explainer:answer" and the usual options (shape, question, facts, style). Any other explainer key is a 404: a cartoon's cast is designed after the run starts, and an ad researches its facts in a step ahead of the writer.

Chats and carousels. chat:<id> (text-message-video) and carousel:<id> (viral-tiktok-carousel), and the house formats those two follow, answer with their writer's contract: { format, preset, kind: "chat" | "slides", chatFormat | carouselFormat, schema, rules, avoid?, hooks: { first, patterns: [{ id, name, does, evidence }], rules, writeLike, gate }, checks, limits, timing, example: { brief, options, script }, send }. rules is the writer's whole prompt for that format and topic, word for word (a test holds it equal to what the writer sends); a chat's avoid is what that account already posted. Query: topic, account (its brand rules and used hooks), opening (pattern:<id>), a chat's tz, a carousel's slides (its length) and product. A written chat is stored as the chat writer stores its thread (THEM's fixed name, the clock picked in code, the texting register unless register: false); a written carousel is finished by the writer's own code at its Write step. Neither asks a model. chat:copy (a copy is drawn verbatim) and the data decks (deck:*, templates over the records they read) take none.
POST/api/v1/formats/{key}/script/checkAPI key

A script you wrote, checked alone: the checks POST /api/v1/flows runs before it starts a run with it. Nothing is stored, started or spent, and no model is called.

Request

{ "brief"?: { "niche", "goal", "platform", … }, "options": { "shape", "question", "facts", "style"?, "account"? },
  "script": { "kind": "explainer", "plan": { "title", "scenes": [{ "purpose"?, "lines": ["…"],
              "shots": [{ "line": 0, "bg"?, "transition"?, "camera"?, "hold"?, "elements": [ … ] }] }] } } }

Response

{ "ok": true, "data": { "passed": false, "error": "every problem, numbered, in words",
  "problems": [{ "check": "schema | limits | structure | facts | figures | first-line | pace | counts | pitch | phone-check | style | copy",
                 "message": "Shot 7 holds one picture over 3.3 s: split its line into lines of at most 7 words, a shot each.",
                 "shots"?: [{ "scene": 3, "shot": 2 }], "lines"?: [{ "scene": 3, "line": 1 }] }],
  "warnings": [ … ], "stats": { "scenes", "lines", "words", "shots", "seconds" } | null } }
Every check the built-in writer's drafts pass — every figure in options.facts, the question asked then answered in line 1, the pace (a shot a line, no picture held past ~3.3 s), the counts, the phone check, the copy gate on the brief and options.account's brand rules — the run's Style's, and the limits the writer's parser would otherwise clip quietly. Shots and lines in messages are counted across the film (scene 1's first); shots and lines map them to your scene and index, 1-based. Warnings don't refuse a script.

A chat (script: { "kind": "chat", "thread", "register"? }) or a carousel ({ "kind": "slides", "slides" }, with productId for its Prop) gets every gate its writer's draft passes: the format's shape (bubble count, whose last, a bare format's empty hook; 3–12 slides, a locked cover), the hook gate on the hook, the first bubble or the cover, the copy gate, the account's brand rules, and a chat's novelty against what the account posted (a warning). problems carry check (schema | limits | shape | hook | copy | brand | novelty), message and where: hook, bubbles or slides (1-based). A passing chat returns the thread as it would be drawn, a carousel its slides as the Write step keeps them.
GET/api/v1/formats/evidenceAPI key

How each recipe and format is doing on one of your accounts: ?goal=reach&accountId=&platform=tiktok&niche=&subNiche=&keys=chat:thread,carousel:myth-bust.

Response

{ "ok": true, "data": { "accountId", "platform", "goal", "metric", "nicheCategory", "subNiche", "scored", "proxied", "unscored",
  "keys": [{ "key": "chat:thread", "n", "hits", "hitRate", "medianScore", "reliableScore", "tier": "reference | trial | supported", "decay"?,
             "prior": { "source": "sub-niche | niche | all | market | none", "p", "posts"?, "accounts"? },
             "posterior": { "alpha", "beta", "mean", "low", "high" } }] } }
A post's score is its goal metric ÷ its account's median over the previous 20 posts at the same age (24 h or 7 d); a hit is 1 or more. Posts are scored once the account has 5 earlier readings — numbers come from the post ledger. Without accountId, all your accounts on the platform (TikTok when platform is left out; a paid placement, meta-paid or tiktok-paid, reads no organic posts: platform: null, every key at its prior). keys adds formats you haven't posted, with their prior only. Priors pool other accounts in the niche (at least 5 accounts and 3 users) — scores only, never anyone's posts or numbers. Paused for now: feedbackPaused: true, nothing new is counted and runs don't pick from it.
GET/api/v1/scriptsAPI key

The curated script-examples library.

Response

{ "ok": true, "data": { "scripts": [{ "id", "title", "script_type", "frames": [ … ], … }] } }
GET/api/v1/scripts/{id}API key

One script example.

Response

{ "ok": true, "data": { /* the example */ } }
POST/api/v1/scriptsAPI key

Create a script example (201). Admin only.

Request

{ "title", "frames": [{ "caption", "visual_description", "use_character" }],
  "script_type"?: "single_image | carousel | video", "source_url"?, "source_platform"?, "viral_notes"?, "preset_id"? }
DELETE/api/v1/scripts/{id}API key

Delete a script example. Admin only.

Response

{ "ok": true, "data": { "id", "deleted": true } }
POST/api/v1/scripts/from-mediaAPI key

A script-example draft from an uploaded video, image or carousel screenshots — frames, plus an autopsy for a single video. Admin only; nothing is saved.

Request

multipart/form-data: files (one or more, in order) or file, title?, sourcePlatform?, niche?

Response

{ "ok": true, "data": { "script": { "title", "source_url", "source_platform", "viral_notes",
  "frames": [{ "caption", "visual_description", "use_character" }],
  "autopsy"?, "hook_text"?, "hook_spoken"?, "hook_verified"?, "inspected"?, "checked_at"? } } }
GET/api/v1/stylesAPI key

The Styles a drawn explainer can take — yours (read from a video) first, then the Library's 32 — each with its workflow, signature features, banned list, palette, faces and covers. ?preset= narrows it to one workflow's. A run takes one as options.style.

Response

{ "ok": true, "data": { "styles": [{ "key": "chart:editorial" | "own:<id>", "name", "note", "preset", "own",
  "signature", "banned", "palette": { "bg", "ink", "accent" }, "faces": { "head", "body", "mono" }, "covers": ["url"] }] } }
POST/api/v1/stylesAPI key

Read a video's look into your own Style for one workflow (~$0.01): a video file's link gives six frames across it, a post's link the picture it shows anyone. Its palette, type, background rule, motion, captions and signature are laid over that workflow's nearest Library Style.

Request

{ "video": "https://…", "family": "map" | "chart" | "cartoon" | "ad" | "figure" | "recon" | "answer", "name"? }

Response

{ "ok": true, "data": { "style": { "key": "own:<id>", … } } }
GET/api/v1/visual-presetsAPI key

Your poses and the Library's (the library account's, everyone's) — each one's picture, prompt, clothing and background lines. Yours first.

Response

{ "ok": true, "data": { "presets": [{ "id", "title", "prompt", "description", "clothing", "background",
  "image_url", "source_url", "owner": "mine" | "library" }] } }
POST/api/v1/visual-presets/analyzeAPI key

Read a pose from a post's link or a picture, before saving it: the picture is kept in our storage and its framing, light, pose and mood, clothing and background are written out.

Request

{ "url": "https://www.tiktok.com/@…/video/…" }   // TikTok, YouTube, Pinterest, any page with a preview image, or an image link
// or { "image_url": "https://…" }               // a hosted screenshot or photo (POST /api/v1/uploads)

Response

{ "ok": true, "data": { "title", "description", "prompt", "clothing", "background", "image_url", "source_url" } }
Instagram and X often hide their pictures from servers: 400 says to send a screenshot instead. One vision call, limited per day without your own key (429). Save it with POST /api/v1/visual-presets.
POST/api/v1/visual-presetsAPI key

Save a pose (201) — yours. library: true adds it to the Library instead (admins only).

Request

{ "title", "prompt", "image_url", "description"?, "clothing"?, "background"?, "source_url"?, "library"? }
DELETE/api/v1/visual-presets/{id}API key

Delete one of your poses (an admin: the Library's too).

Response

{ "ok": true, "data": { "id", "deleted": true } }

Motions

Short clips an Expert is put in. Yours are uploads — your own clip or one you saved; a link isn't taken. The Library's include Trending now: this week's worldwide moves, cut and with the creator's mark taken off, each with its trend (the move, its regions, the sound to post with). Yours and the Library's. Two modes: Replace the character — the Expert's full body takes the place of the person in the clip, its scene, camera and sound kept; or Copy the moves (motion transfer) — only the movement is borrowed, the Expert, their clothes and the scene come from one of their photos, their face held by their passport, the clip's sound dropped.

GET/api/v1/motionsAPI key

Your Motions, then the Library's.

Response

{ "ok": true, "data": { "motions": [{ "id", "title", "video_url", "poster_url", "seconds", "start", "sourceSeconds", "width", "height", "owner": "mine" | "library", "trend": null | { "key", "title", "kind", "howTo", "soundTitle", "soundUrl", "original", "regions", "stage", "handle", "sourceUrl" }, "created_at" }] } }
POST/api/v1/motionsAPI key

Keep an uploaded clip as a Motion (201) — an MP4, MOV or WebM uploaded first with POST /api/v1/uploads (or /api/v1/uploads/multipart past 9 MB). A clip longer than 30 s becomes the 30 s window from start.

Request

{ "video_url": "https://…/videos/<you>/uploads/<id>.mp4", "title"?, "seconds"?: 48.2, "start"?: 12, "width"?, "height"?, "library"? }   // seconds: the file's length · library: admins
PATCH/api/v1/motions/{id}API key

Rename one of your Motions (an admin: the Library's too).

Request

{ "title": "…" }
DELETE/api/v1/motions/{id}API key

Delete one of your Motions (an admin: the Library's too). Clips made from it stay.

Response

{ "ok": true, "data": { "id", "deleted": true } }
GET/api/v1/motions/stillsAPI key

The pictures an Expert can be put in a Motion from: their Workbench photos, newest first, their full body and face.

Request

?expert=<slug>

Response

{ "ok": true, "data": { "name", "passport", "fullBody", "photos": ["https://…"] } }
POST/api/v1/motions/{id}/stillAPI key

Make a photo of an Expert to move in this Motion (201): full length, hands free, in an ordinary room, kept with their photos.

Request

{ "expertSlug": "bram" }

Response

{ "ok": true, "data": { "imageUrl": "https://… pass it to /animate" } }
One photo through the photo gate: your own Gemini key, or one of your free photos.
POST/api/v1/motions/{id}/animateAPI key

Put an Expert in a Motion (202), on your own fal.ai key: in place of the person in it (mode replace — Wan 2.2 Animate Replace, about $0.08 a second of clip), or performing its movement in the photo you pick (mode moves, the default — Kling v3 Standard Motion Control, about $0.126 a second).

Request

{ "expertSlug": "bram", "mode"?: "replace" | "moves", "imageUrl"?: "https://… one of theirs (GET /api/v1/motions/stills) — what goes in; replace defaults to their full body", "prompt"?: "deadpan the whole time — moves only" }

Response

{ "ok": true, "data": { "jobId", "estimatedUsd" } }
replace takes the Expert's full body on white (else their newest photo) as it is and keeps the clip's scene, camera and sound — one shot only, no cuts. moves needs imageUrl and drops the sound. Poll GET /api/v1/bricks/jobs/{jobId} — a few minutes. 402 without a fal.ai key (add it in Settings); 404 for a Motion or Expert you can't see; 400 for a picture that isn't the Expert's, or an Expert with neither a full body nor a photo to replace with.
GET/api/v1/motions/clipsAPI key

The clips your Experts performed, and the ones still rendering, newest first.

Response

{ "ok": true, "data": { "clips": [{ "id", "status": "rendering" | "done" | "failed", "url", "motionId", "expert", "mode": "replace" | "moves", "poster", "seconds", "error", "createdAt" }] } }

Storyboards

A sequence of frames — caption, visual description, image — for carousels and character stories. A frame has no id: it's addressed by its index, and every write answers with the whole storyboard so you see the new indices.

GET/api/v1/storyboards/presetsAPI key

The viral storyboard presets.

Response

{ "ok": true, "data": { "presets": [{ "id", "name", "description", "category", "icon",
  "frames": [{ "caption", "visual_description", "use_character"? }] }] } }
GET/api/v1/storyboardsAPI key

Your storyboards, newest first.

Response

{ "ok": true, "data": { "storyboards": [{ "id", "name", "persona_id", "image_ids", "frames", "created_at", "updated_at" }] } }
POST/api/v1/storyboardsAPI key

Make a storyboard (201) — empty, from gallery images, from a first and last frame, from a preset, or from a script example.

Request

{ "from": "empty", "name"?, "personaSlug"? }
{ "from": "images", "imageUrls": ["gallery image URLs"], "name"?, "personaSlug"? }
{ "from": "prompt", "firstFrameText", "lastFrameText", "totalFrames"?: 3 | 5 | 7 | 9, "name"?, "personaSlug"? }
{ "from": "preset", "presetId", "name"?, "personaSlug"? }
{ "from": "script" | "inspired-by-script", "scriptId": "a script example (GET /api/v1/scripts)", "name"?, "personaSlug"? }

Response

{ "ok": true, "data": { "id", "storyboard": { "id", "name", "persona_id", "image_ids", "frames", "created_at", "updated_at" },
  "resolvedFrames": [{ "frame": { "caption"?, "visual_description"?, "image_id"?, "is_first"?, "is_last"?,
                                  "use_character"?, "use_previous_image"? }, "image": { "id", "url", … } | null }],
  "personaSlug": "string | null",
  "framesNeedingImage": [2, 3] } }
The AI kinds (prompt, script, inspired-by-script, and preset with a persona) take one text rate-limit slot and run synchronously (~5–30 s).
GET/api/v1/storyboards/{id}API key

One storyboard with its frames resolved to images. framesNeedingImage lists frames with a visual description and no image.

Response

{ "ok": true, "data": {
  "storyboard": { "id", "name", "persona_id", "image_ids", "frames", "created_at", "updated_at" },
  "resolvedFrames": [{ "frame": { "caption"?, "visual_description"?, "image_id"?, "is_first"?, "is_last"?,
                                  "use_character"?, "use_previous_image"? }, "image": { "id", "url", … } | null }],
  "personaSlug": "string | null",
  "framesNeedingImage": [2, 3]
} }
PATCH/api/v1/storyboards/{id}API key

Rename it, or link a persona (null detaches).

Request

{ "name"?: "string | null", "personaSlug"?: "string | null" }

Response

{ "ok": true, "data": { "id", …the GET shape } }
DELETE/api/v1/storyboards/{id}API key

Delete a storyboard (its images stay in your gallery).

Response

{ "ok": true, "data": { "id", "deleted": true } }
POST/api/v1/storyboards/{id}/fillAPI key

Write frames with AI: rewrite them from a first and last frame, or fill every empty frame from the frames around it.

Request

{ "mode": "prompt", "firstFrameText", "lastFrameText", "totalFrames"?: 3 | 5 | 7 | 9, "personaSlug"?: "string | null" }
{ "mode": "empty-frames" }

Response

{ "ok": true, "data": { "id", …the GET shape } }
One text rate-limit slot per call; synchronous (~5–30 s).
POST/api/v1/storyboards/{id}/imagesAPI key

Append gallery images as new frames, in order (repeats and images already on it are skipped).

Request

{ "imageUrls": ["gallery image URLs"] }

Response

{ "ok": true, "data": { "id", …the GET shape } }
POST/api/v1/storyboards/{id}/framesAPI key

Append a frame (201). An empty body adds an empty frame.

Request

{ "caption"?, "visual_description"?, "use_character"?: true, "use_previous_image"?: true, "image_url"?: "a gallery image URL" }

Response

{ "ok": true, "data": { "id", "index": 4, …the GET shape } }
PATCH/api/v1/storyboards/{id}/frames/{index}API key

Edit a frame. role marks it first (moved to 0) or last (moved to the end), or clears the mark.

Request

{ "caption"?, "visual_description"?, "use_character"?, "use_previous_image"?,
  "image_url"?: "a gallery image URL | null", "role"?: "first | last | null" }   // at least one

Response

{ "ok": true, "data": { "id", "index": "its index afterwards", …the GET shape } }
PUT/api/v1/storyboards/{id}/frames/orderAPI key

Reorder: order[i] is the current index of the frame that should end up at i — every index once. First/last frames stay pinned.

Request

{ "order": [2, 0, 1] }

Response

{ "ok": true, "data": { "id", …the GET shape } }
POST/api/v1/storyboards/{id}/frames/{index}/generateAPI key

Make one frame's image (no body): continues the story from an earlier frame's image, or renders its visual description with the linked persona.

Response

{ "ok": true, "data": { "id", "index", "generated": true, "imageUrl", …the GET shape } }
Synchronous, ~15–60 s; one image slot. To make every missing image, call it for each index in framesNeedingImage, in order, stopping at the first failure.

Workflows

Every workflow is a preset of one flow of bricks — brief, cast, write, voice, picture, the preview, animate, cut, deliver. Start a run, follow it, fix what you don't like before the preview, then approve: video only ever starts after that, unless the run was started straight through.

GET/api/v1/presetsAPI key

Every workflow's preset: its steps, what a run needs, the options its steps read, and an example POST /api/v1/flows body.

Response

{ "ok": true, "data": {
  "presets": [{ "slug", "title", "guide", "guideUrl", "handsOff",
    "steps": [{ "index", "gate": false, "key", "brick", "variant", "title", "label", "cost", "needs", "makes", "options" }
             | { "index", "gate": true, "title" }],
    "setup": { "brief": "full | product-only | none", "creator" | "product" | "appScreen" | "recording" | "motion": "required | optional | none",
               "topic", "gate", "video": { "engine": "veo", "tier" } | { "engine": "lipsync" } | { "engine": "motion" } | null },
    "options": [{ "key", "type", "values"?, "default"?, "description", "readBy", "presetValue"? }],
    "example": { /* a POST /api/v1/flows body */ } }],
  "brief": { /* the brief's fields */ }, "body": { /* the POST /api/v1/flows body */ }
} }
GET/api/v1/presets/{slug}API key

One workflow's preset (404 for an unknown slug).

Response

{ "ok": true, "data": { "preset": { … }, "brief": { … }, "body": { … } } }
POST/api/v1/flowsAPI key

Start a run of a workflow (201). Hands-off by default: each step starts when the one before it is ready, up to the preview.

preset is a workflow slug: creator-ugc-video, testimonial-video, tiktok-reels-short-form, app-demo-video, product-demo-video, lipsync-ugc-video, animated-story-ad, drama-song-ad, viral-tiktok-carousel, text-message-video, screen-recording-video (your own recording in recordingUrl, a payout screenshot in proofUrl; options.filmed phone or tablet shows it filmed on its device over the shoulder instead of flat), youtube-clips (YouTube to Shorts: your long video's link in options.sourceUrl; options.clipCount clips, 1–15, default 8, each options.clipMinSeconds–options.clipMaxSeconds long, default 20–60 — picked from its captions, tightened, framed on the speaker and captioned on the worker; it waits before the cut (awaiting: "input") until you keep the moments worth a clip with POST /api/v1/flows/{id}/script { "kind": "moments", "keep": [0, 2] } (places in script.meta.moments; all of them for every clip) — or start it with straightThrough: true to cut them all; every clip lands in your gallery and the run's video is the best-ranked; Whisper on your fal key gives exact word times), character-in-a-trend (an Expert in creatorSlug put in a Motion — motionId, yours or the Library's — by options.motionMode: replace, their full body in place of the person in the clip, its scene and sound kept, one shot only (Wan, ≈$0.08/s), or moves, the default — they perform its movement in a still: options.photoUrl, options.lookId, options.fullBody (a new head-to-feet photo, hands free) or their newest photo (Kling, ≈$0.126/s, silent); on your fal key, priced at the preview), the photo packs (product-ugc-photos, amazon-listing-pack, shopify-product-pack, before-after-photo-pack), text-post (a post or thread for X, Bluesky or LinkedIn: options.surface, options.thread, options.link) or answer-explainer (format explainer:answer: one searched question answered in 30–50 s, 9:16 and 16:9 — options.question as it's searched, options.shape what-is · how-to · how-it-works · vs · worth-it · alternatives · does-it-work · price · facts · for-who, options.style answer:dot-matrix · answer:ticker · answer:editorial · answer:paper (cards of paper on a lit desk, rendered with real light where the worker has Blender), answer:receipts · answer:collage · answer:hero (the house kit, drawn in Chromium: a handed-in script's shots carry visual — source { url, quote, publisher, date } for the real page, photo and cutout searches — see the script contract), and options.facts, at least two lines — it has no research step, so a run without them is a 400, and a film saying a figure the facts don't give fails; write the script yourself and send it as script: { "kind": "explainer", "plan" } — GET /api/v1/formats/explainer:answer/script says how — and no model writes: it is checked first, and a plan that breaks a rule is a 400 with problems [{ check, message, shots?, lines? }], nothing stored or spent). A chat (chat:<id>) or a carousel (carousel:<id>) you wrote yourself goes the same way — script: { "kind": "chat", "written": true, "thread" } or { "kind": "slides", "slides" }, checked against every gate the writer's draft passes and refused with problems [{ check, message, hook?, bubbles?, slides? }]. Give the brief filled in, a saved briefId, or a link / description in briefSource — the run reads it first. A body missing what the preset needs (its setup) is a 400. straightThrough: true makes the video without stopping at the preview, for this run only. Or start a format by its key instead of a preset: format is a catalogue key from GET /api/v1/formats (house:<slug>, a recipe key like explainer:map, talking:* to let the writer pick the shape, or ref:<id>) — the workflow and its options come from the format. Add project and format may be one of the project's own formats; what the body leaves out comes from the project's settings.make (the account, product, niche, Expert, App, Prop, screen recordings), and a two-voice format gets the project's next Expert as its second voice.

Request

{
  "preset": "creator-ugc-video",
  // …or, instead of preset: "format": "explainer:map | house:<slug> | talking:* | ref:<id> | a project's format key", "project"?: "bae"
  "brief"?: { "niche", "goal", "platform", "product"?, "productId"?, "audience"?, "language"?, "nicheOverride"?, "subNiche"? },
  "briefSource"?: { "mode": "url" | "description", "value": "string" },
  "briefId"?: "uuid (a saved brief)",
  "creatorSlug"?: "string (yours)",
  "productId"?: "uuid (one of your /api/v1/props)",
  "appId"?: "uuid (one of your /api/v1/apps — app-demo-video)", "appScreen"?: 0, "appScreenUrl"?: "https://… (or a screenshot)",
  "appScreens"?: [0, 2, 3] (2–4 of the app's screens, in order: a line and a clip each; options.lines types them),
  "recordingUrl"?: "https://… (screen-recording-video: your MP4 / MOV / WebM, ≤ 3 min — upload it first)", "proofUrl"?: "https://… (optional: the payout screenshot, the cover)",
  "motionId"?: "uuid (character-in-a-trend: a Motion, yours or the Library's — GET /api/v1/motions)",
  "script"?: { "kind": "chat", "thread": { … }, "copiedFrom"?, "dropped"? } (text-message-video: a chat copied line for line,
             from POST /api/v1/chat/transcribe — no writer, every message kept, up to 90 s at its own pace)
             | { "kind": "explainer", "plan": { "title", "scenes": [ … ] } } (explainer:answer: the script you wrote,
             GET /api/v1/formats/explainer:answer/script — checked first, no writer)
             | { "kind": "chat", "written": true, "thread": { "hook", "contact"?, "messages": [ … ] }, "register"?: false }
               (chat:<id>: a chat you wrote to GET /api/v1/formats/chat:<id>/script — checked first, no writer)
             | { "kind": "slides", "slides": [{ "caption", "visualPrompt", "card"?, "pose"? }] }
               (carousel:<id>: a carousel you wrote to GET /api/v1/formats/carousel:<id>/script — checked first, no writer),
  "options"?: { "line"?, "seconds"?, "voice"?, "tier"?: "lite | fast | full" (ignored — Gemini Omni), "captions"?, "hookFirst"?, "account"?,
                "opening"?: "the hook to open on, the topic in [brackets]", … },
  // An answer explainer — "format": "explainer:answer", no project needed:
  //   "brief": { "niche": "What Is a Melamine Sponge?", "goal": "reach", "platform": "shorts" },
  //   "options": { "shape": "what-is", "question": "What is a melamine sponge?", "style"?: "answer:dot-matrix | answer:ticker | answer:editorial | answer:paper | answer:receipts | answer:collage | answer:hero",
  //                "facts": "- <claim> (<source title>, <date>)\n- …" (≥ 2 lines; every figure the film says must be one of them) }
  // The data carousels (whats-inside-carousel, app-carousel, catalog-carousel) — free, no preview:
  //   "options": { "source": { "kind": "prop", "propId" } | { "kind": "apps", "appIds": [ … ] } | { "kind": "catalog", "catalogId" }
  //                  | { "kind": "inline", "name", "url"?, "box"?, "items": [{ "key", "title", "price"?, "worth"?, "rating"?, "images": ["https://…"], … }] } (a box or a list, handed in whole),
  //                "recipe"?: "inside | worth-it | app-list | app-review | whats-new | app-how-to | top | under | new-in | on-sale | brand | versus | gift-guide | tiers | resale | editions",
  //                "deckParams"?: { "count", "maxPrice", "brand", "audience", "itemKeys", "theme", "steps", "ownSlot", "days" },
  //                "houseFormat"?: "house:<a list, ranking or side-by-side format>",
  //                "coverPhoto"?, "coverQuery"?, "headline"?, "kicker"?, "outro"?, "itemLabel"?, "lead"?, "worthLabel"?, "shop"? }
  "auto"?: true,
  "straightThrough"?: false,
  "name"?: "string"
}

Response

{ "ok": true, "data": { "runId": "uuid" } }
Video steps need the Creator plan and your own Gemini key. GET /api/v1/presets lists every option. options.opening — a hook from GET /api/v1/hooks, or a hook test's winner — is what the writer builds the first line, cover or headline on; a running hook test on options.account sets it instead. options.hookPattern (or an opening of pattern:<id>) opens on one measured hook pattern instead: stakes, number, answer-first, question, contradiction, doing-it-wrong, scenario, confession, call-out, mid-scene or ask-the-viewer; each recorded post carries picked.hookPattern { given, written }.
GET/api/v1/flowsAPI key

Your runs, newest first, with where each stands. ?limit= (1–200, default 50).

Response

{ "ok": true, "data": { "runs": [
  { "runId", "name", "preset", "state": "working | waiting | failed | done",
    "awaiting": "gate | hook | input | retry | null", "step": "Frames | null",
    "video": "url | null", "thumb": "url | null", "createdAt", "finishedAt" }
] } }
GET/api/v1/flows/{id}API key

One run: every step and its state, what it made, the preview's price, its jobs — and next, the call that moves it on.

Response

{ "ok": true, "data": {
  "runId", "name", "preset": { "slug", "title", "guide" },
  "steps": [{ "index", "gate", "key", "brick", "variant", "title", "cost",
              "status": "todo | running | ready | approved | failed | waiting", "error"?, "jobId"? }],
  "current": 4, "awaiting": "gate | hook | input | retry | null", "auto": true, "straightThrough": false,
  "brief", "cast", "script": { "id", "variant", "lines", "hook", "meta" },
  "takes": [ … ], "frames": [{ "id", "kind", "url", "use": { "line", "seconds" }, "meta" }], "clips": [ … ], "cut": { … } | null,
  "estimate": { "usd": 0.81, "seconds": 8, "clips": 2, "engine": "veo" },
  "hookFirst", "silentClips", "hookApprovedAt", "clipsFailed", "aspect", "jobs": [ … ], "finishedAt",
  "next": { "action": "done | approve | retry | start-step | wait", "message", "step"?, "call"? }
} }
PATCH/api/v1/flows/{id}API key

Hands-off on or off; straight through the preview, for this run (403 without Creator and your Gemini key).

Request

{ "auto"?: boolean, "straightThrough"?: boolean }

Response

{ "ok": true, "data": { "runId", "outcome": { … } | null } }
DELETE/api/v1/flows/{id}API key

Delete a run you own. What it made stays in your gallery.

Response

{ "ok": true, "data": { "runId" } }
POST/api/v1/flows/{id}/approveAPI key

Approve what the run waits on: the preview (awaiting gate) — the one door to video, at the server's price — or, past it, the hook clip (awaiting hook).

Response

{ "ok": true, "data": { "runId", "outcome": { "state": "running", "step": 5 } } }
With 3 or more clips the hook clip renders first and the run waits with awaiting: "hook" — approve again for the rest (or remake the hook first with /steps). Start with options.hookFirst: false to render every clip at once. 400 when nothing waits; 403 without Creator and your Gemini key.
POST/api/v1/flows/{id}/stepsAPI key

Start a step by hand — the next one, or a failed one again — or make one item of it again (a take, a frame, a shot, a slide, a clip) (201).

Request

{ "step": 3, "item"?: 1 }

Response

{ "ok": true, "data": { "jobId": "uuid" } }
Before the preview is approved, anything before it can be made again; nothing past it starts until it's approved.
POST/api/v1/flows/{id}/scriptAPI key

Change the run's script before any video. What it makes stale (frames, takes, the story's character, a chat's recording) is made again.

Request

{ "kind": "talking", "script": { … } }   // a runner-up (script.meta.runnersUp[n]) or edited lines
{ "kind": "slides", "slides": [{ "role": "cover | body | cta", "caption", "visualPrompt",
                                 "featuresCreator"?, "render"?: "image | template" }] }
{ "kind": "story", "script": { … } }     // a narrated story (script.meta.script edited)
{ "kind": "chat", "thread": { "hook", "timestamp"?, "contact"?, "messages": [{ "from": "me | them", "text" }] } }

Response

{ "ok": true, "data": { "scriptId" } }
Refused once the preview is approved.
POST/api/v1/flows/{id}/framesAPI key

Put a photo from your gallery in place of the run's picture at index at — a pack shot, a slide, a storyboard frame, or a video frame before approval.

Request

{ "at": 0, "url": "https://… (a gallery image)" }

Response

{ "ok": true, "data": { "frameId" } }   // swapped at once
{ "ok": true, "data": { "jobId" } }     // a persona's frame is redone from the photo — poll the job
To make a frame again from scratch instead: /steps with { step, item: at }.
POST/api/v1/flows/{id}/captionAPI key

The post's caption, written from what the run made — a video's from its script, a carousel's from its slides — or, with a surface, its X, Bluesky or LinkedIn post. Nothing is stored.

Request

{}                                          // the caption
{ "surface": "x | bluesky | linkedin", "thread"?: 1-8, "link"?: "https://…" }   // the post

Response

{ "ok": true, "data": { "caption": { "text", "hashtags", "disclosure" } } }
{ "ok": true, "data": { "post": { "surface", "posts": ["string"], "reply": "string | null" } } }
Same daily limit as the caption writer (429).
POST/api/v1/flows/{id}/variantAPI key

An Animated Story Ad again as a new run with another opening (201) — only the opening is made, after its own preview.

Request

{ "opening": { "narration", "action", "visual", "angle", "colorState", … } }   // from /api/v1/story-ad/hooks

Response

{ "ok": true, "data": { "runId", "kept": 3 } }   // kept: clips carried over
POST/api/v1/flows/randomAPI key

Create random UGC: a Creator UGC Video run on a topic picked for the persona, optionally starting from one of their photos (201).

Request

{ "personaSlug": "string", "anchorImageUrl"?: "https://… (a gallery photo)" }

Response

{ "ok": true, "data": { "runId" } }

Schedules & posting

Workflows that start themselves on a timetable — a product-feed carousel every Wednesday — the finished work waiting to be posted, for whatever posts it (a phone, a scheduler, a person), and the post ledger: what went out, on which account, made from what, and the numbers typed from each platform's insights — paused for now: recording and numbers answer 409. Only workflows that generate nothing paid can be scheduled — the data carousels and text-message videos; anything that makes pictures or video is refused, so nothing spends unattended.

POST/api/v1/schedulesAPI key

Schedule a workflow (201). Each run starts hands-off; `rotate` lays one option set over the setup per run, in turn. Up to 20.

Request

{
  "preset": "catalog-carousel",
  "name"?: "string",
  "weekdays"?: [3] (0 = Sunday … 6; none = every day), "hour"?: 9 (UTC),
  "setup": { "productId"?, "creatorSlug"?, "appId"?, "briefId"?, "brief"?, "options"?,   // as POST /api/v1/flows
             "topicSource"?: "trending" },   // a new trending topic each run (a text-message video)
  "rotate"?: [{ "deckParams": { "audience": "her" } }, { "deckParams": { "audience": "him" } }],
  "enabled"?: true
}

Response

{ "ok": true, "data": { "id", "preset", "name", "setup", "rotate", "weekdays", "hour", "enabled", "next_run_at",
                          "last_run_at", "last_run_id", "last_error", "runs_made" } }
setup.topicSource: "trending" — for a workflow that writes from a topic — gives every run a trending topic in the schedule's niche (brief.nicheOverride, else the niche of the posting account in options.account; see GET /api/v1/trends) that its last 20 runs didn't use: it goes into that run's options.topic and brief, and the setup stays as saved. The brief then needs no topic of its own.
GET/api/v1/schedulesAPI key

Your schedules.

Response

{ "ok": true, "data": { "schedules": [ … ] } }
PATCH/api/v1/schedules/{id}API key

Change name, weekdays, hour, setup, rotate or enabled — the next start is worked out again.

Response

{ "ok": true, "data": { /* the schedule */ } }
POST/api/v1/schedules/{id}/runAPI key

Start its next turn now (201); the timetable is unchanged.

Response

{ "ok": true, "data": { "runId" } }
DELETE/api/v1/schedules/{id}API key

Delete a schedule; the runs it made stay.

Response

{ "ok": true, "data": { "id", "deleted": true } }
GET/api/v1/posts/readyAPI key

Finished work nobody has posted yet, newest first: ?limit=20&since=<ISO time>.

Response

{ "ok": true, "data": { "posts": [{ "runId", "clientRef", "preset", "title", "name", "kind": "carousel | video | photos",
                                   "finishedAt", "images" (a carousel's slides, in order), "video", "caption" (hashtag-free),
                                   "hashtags", "sound", "aiGenerated", "scheduleId" }] } }
POST/api/v1/flows/{id}/postedAPI key

Report where a run went out — it leaves the ready list and lands in the post ledger. One call per platform.

Request

{ "url": "https://www.tiktok.com/@you/photo/…", "platform"?: "tiktok", "handle"? | "accountId"? }

Response

{ "ok": true, "data": { "posted": [{ "url", "platform", "at" }], "postId" } }
The account is read from a TikTok address when neither is given. Log the post's numbers with POST /api/v1/posts/{postId}/readings.
GET/api/v1/postsAPI key

The post ledger, newest first: ?accountId=&runId=&platform=&limit=50&before=<ISO time>. accountId takes one account or several, comma-separated (posts on any of them). Removed posts are left out.

Response

{ "ok": true, "data": { "posts": [{
  "id", "account_id", "platform", "post_url", "platform_post_id", "posted_at", "status", "via", "run_id", "asset_id",
  "recipe_key": "chat:thread | carousel:myth-bust | talking:confession | …", "format_key", "medium", "goal",
  "niche_category", "sub_niche", "structure_type", "hook_family", "hook_text", "topic", "caption", "sound",
  "readings": [{ "id", "window_label": "24h | 7d | adhoc", "age_h", "metrics", "note", "captured_at" }],
  "due": ["24h" | "7d"]   // old enough to read, no numbers yet
}] } }
POST/api/v1/postsAPI key

Record something that went out (201). What made it — recipe, hook, topic, goal, niche — is taken from the work now and kept. The same address twice is one post. Paused for now: answers 409.

Request

{
  "url": "https://…",                  // required unless status "queued"
  "platform"?: "tiktok | instagram | facebook | youtube | pinterest",   // read from the url
  "accountId"? | "handle"?,            // a TikTok url names its own
  "runId"? | "assetId"? | "source"?: { "table": "videos | mascot_videos | assets", "id" },
  "postedAt"?, "caption"?, "sound"?, "status"?: "posted | queued", "externalRef"?
}

Response

{ "ok": true, "data": { /* the post */ } }
A run is better reported with /api/v1/flows/{id}/posted, which also takes it off the ready list.
GET/api/v1/posts/{id}API key

One post with its readings and what's due.

Response

{ "ok": true, "data": { /* the post, readings, due */ } }
PATCH/api/v1/posts/{id}API key

Change status, url, postedAt or accountId (null for the platform's unnamed account). Status removed takes it out of the list and the results.

Request

{ "status"?: "posted | queued | failed | removed", "url"?, "postedAt"?, "accountId"? }

Response

{ "ok": true, "data": { /* the post */ } }
POST/api/v1/posts/{id}/readingsAPI key

A post's numbers, typed from the platform's insights (201). Typing the same window again replaces it; a field left out stays unknown, never zero. Paused for now: answers 409.

Request

{ "window"?: "24h | 7d | adhoc", "ageH"?: 26 (hours since posting — sets the window),
  "metrics": { "views", "likes"?, "comments"?, "shares"?, "saves"?, "avgWatchPct"?, "follows"?, "clicks"?, "reach"?, "purchases"? },
  "note"?, "source"?: "manual | phone-poster" }

Response

{ "ok": true, "data": { "id", "window_label", "age_h", "source": "manual | phone-poster", "metrics", "captured_at" } }
views is required. Read at 24 hours and at 7 days — a reading 12–48 h in counts as 24h, from 5 days as 7d. source left out: a reading with ageH of a post phone-poster posted is phone-poster's, anything else typed. The two are kept apart at the same window and merged when read, phone-poster's numbers first.
GET/api/v1/accountsAPI key

Your posting accounts — one platform, one handle. Results are kept per account.

Response

{ "ok": true, "data": { "accounts": [{ "id", "platform", "handle", "niche_category", "sub_niche", "connection_id",
                                      "phone_account_id", "external_id", "is_house", "rules", "created_at" }] } }
POST/api/v1/accountsAPI key

Add a posting account (201) — or get the existing one: handles match by letters and digits, so @advent_center and advent.center are one account.

Request

{ "platform": "tiktok | instagram | facebook | youtube | pinterest", "handle", "nicheCategory"?, "subNiche"? }

Response

{ "ok": true, "data": { /* the account */ } }
Connecting a Facebook Page or Instagram account makes one; recording a post with a handle does too.
PATCH/api/v1/accounts/{id}API key

Change handle, nicheCategory or subNiche — what the account is about — or its brand rules.

Request

{ "handle"?, "nicheCategory"?, "subNiche"?, "isHouse"?,
  "rules"?: { "never"?: string[], "tone"?: string, "notes"?: string, "product"?: "caption" } }

Response

{ "ok": true, "data": { /* the account */ } }
rules is replaced whole (send {} to clear): up to 40 never phrases the copy may not contain (checked, and reworded when a draft has one), a tone, other rules in notes, one per line, and product: "caption" — the product is named only in the post's caption (no slide, message or spoken line names or uses it; checked on the copy, and formats whose recipe names it in the post are switched off in the account's projects). Every writer follows them when a run or brief names the account (options.account or brief.accountId). isHouse marks one of ppl.studio's own accounts — admins only (403 otherwise).
POST/api/v1/hook-testsAPI key

Start a hook test (201): one format held still on one posting account while two or three hooks take turns opening its runs.

Request

{ "accountId", "preset": "text-message-video | viral-tiktok-carousel | creator-ugc-video | tiktok-reels-short-form |
            animated-story-ad | lipsync-ugc-video | screen-recording-video",
  "arms": [{ "shape": "if your situationship does [this]…", "family"?, "source"?, "example"? }, …]   // 2–3
  "goal"?: "reach | saves | comments | follows | clicks | sales", "name"?, "minPosts"?: 3, "maxPosts"?: 8 }

Response

{ "ok": true, "data": { "id", "accountId", "preset", "goal", "name", "arms": [{ "id": "A | B | C", "shape", "family", "source", "example" }],
                   "status": "running", "winner": null, "decisionReason": null, "minPosts", "maxPosts", "decidedAt", "createdAt" } }
While it runs, every run of that workflow made for the account (options.account) takes the arm with the fewest runs, and its writer builds the opening on the arm's shape — the topic goes in the [brackets]. A post reported from the run carries its arm. One running test per account and workflow (409 otherwise). Hold everything else still: same format, same posting times.
GET/api/v1/hook-testsAPI key

Your hook tests: ?accountId=&status=running|decided|stopped.

Response

{ "ok": true, "data": { "tests": [ /* as above */ ] } }
GET/api/v1/hook-tests/{id}API key

One test with its results per arm and what they say.

Response

{ "ok": true, "data": { /* the test */, "results": [{ "armId", "runs", "posts", "scored", "medianScore",
  "posterior": { "mean", "low", "high" }, "pBest" }],
  "decision": { "state": "collecting | winner | tie", "winner"?, "reason" } } }
A post is scored the way Tune scores its arms: views at 24 h (else 6 h) against the account's usual of the 14 days before, with interest, engagement and watch time weighed in where the platform gives them, then read on a log scale (the factor model's: a 4× post counts for more than a 1.01× one; posterior is the arm's mean as a multiple of the usual). An arm wins once every arm has minPosts scored posts and it is at least 90% likely the best; with every arm at maxPosts and none that clear, it's a tie. A running test with an answer is decided on this read (and on the account's next run): status: "decided", the winner (null on a tie — then no hook opens the runs) and decisionReason.
PATCH/api/v1/hook-tests/{id}API key

Stop a test, or promote its winner — which then opens the account's runs of that workflow (options.opening).

Request

{ "status": "stopped" } | { "status": "decided", "winner": "A | B | C" }

Response

{ "ok": true, "data": { /* the test */ } }
GET/api/v1/reviewAPI key

The weekly review: ten posts from the last 7 days — the five the judge scored highest (else the highest 24h views against the account's usual), then five at random, the same ten all week — with any review already given and the brand-rule suggestions waiting.

Response

{ "ok": true, "data": { "week": "2026-W46", "since", "ready",
  "posts": [{ "postId", "pickedFor": "judge | ratio | random", "judge", "judgeReason", "ratio", "views", "views24", "platform",
              "postUrl", "postedAt", "account": { "id", "handle", "platform" } | null, "caption", "hook", "topic", "formatKey", "runId",
              "media": { "video", "images" }, "review": { "verdict", "why", "kind", "suggestion", "neverPhrase", "suggestionStatus", "updatedAt" } | null }],
  "suggestions": [{ "id", "postId", "why", "suggestion", "neverPhrase", "account", "createdAt" }] } }
POST/api/v1/reviewAPI key

Review a post: up or down, and an optional line of why. Reviewing it again replaces the review.

Request

{ "postId", "verdict": "up | down", "why"?: "never end on a question" }

Response

{ "ok": true, "data": { "id", "postId", "verdict", "why", "kind": "rule | taste | null", "suggestion", "neverPhrase",
                   "suggestionStatus": "pending | accepted | dismissed | null", "updatedAt" } }
The line is sorted by one text-model call: a rule waits as a brand-rule suggestion (accept it below); taste becomes an example the judge reads for that format.
PATCH/api/v1/review/suggestions/{id}API key

Accept a suggested brand rule into the reviewed post's account's rules — an exact phrase onto never-say, else a line of notes — or dismiss it.

Request

{ "status": "accepted | dismissed", "rule"?: "your own wording" }

Response

{ "ok": true, "data": { "id", "status", "accountId" } }

Engine — bricks & jobs

The eight bricks every workflow is built from, callable one job at a time — the queue the Voice, Editor, Animate and Picture pages use.

GET/api/v1/bricksAPI key

The brick catalog: every variant, what it costs and needs, and the JSON Schema of its input.

Response

{ "ok": true, "data": {
  "bricks": ["brief", "cast", "write", "voice", "picture", "animate", "cut", "deliver"],
  "variants": [{ "brick", "variant", "key", "label", "cost": "free | cheap | video", "needs", "makes",
                 "lane": "io | cpu", "usesVeo", "maxAttempts", "runnable", "fromRun", "inputSchema", "schemaError"? }]
} }
runnable variants start as jobs below; fromRun ones read their input from a run — start those with POST /api/v1/flows/{id}/steps. cost: video needs Creator and your Gemini key; usesVeo jobs render one at a time per user.
POST/api/v1/bricks/jobsAPI key

Start one brick as a job of its own (201).

Request

{ "brick": "voice", "variant": "string", "input": { /* matches the variant's inputSchema */ },
  "op"?: "run | redo", "item"?: 0 }

Response

{ "ok": true, "data": { "jobId", "existing": false } }
A runId is refused (400): a run's steps start from the run, with POST /api/v1/flows/{id}/steps. Video bricks: 403 without Creator and your Gemini key. Rate-limited text bricks answer 429. A chat you already have becomes a video with cut / chat and { "thread": { "hook", "messages": [{ "from": "me | them", "text" }] }, "seconds"?, "theme"? } — no model, no cost.
GET/api/v1/bricks/jobsAPI key

?runId= — a run's jobs; or ?standalone=1&brick=&variant=&status=&limit= — your recent jobs (status: comma-separated, or live).

Response

{ "ok": true, "data": { "jobs": [{ "id", "brick", "variant", "runId", "status", "progress", "output", "error", "createdAt", "finishedAt" }] } }
GET/api/v1/bricks/jobs/{id}API key

Poll one job until done, failed or cancelled. What it made is in output and in /api/v1/assets.

Response

{ "ok": true, "data": { "id", "brick", "variant", "runId",
  "status": "queued | running | waiting | done | failed | cancelled",
  "progress": { "stage", "message", "done"?, "total"?, "updatedAt" }, "output", "error", "createdAt", "finishedAt" } }
DELETE/api/v1/bricks/jobs/{id}API key

Stop a job that hasn't finished.

Response

{ "ok": true, "data": { "cancelled": true } }   // false when it had already ended

Videos

Standalone video jobs — enqueue, then poll the statusUrl or take a callback. A whole video from a brief is a workflow run (above).

POST/api/v1/videos/assembleAPI key

Concat up to 8 clip URLs into one 9:16 MP4, with optional burned captions and upscale (202).

upscaleTo: 1080p (default) / 4k / none. For captions set burnSubtitles and pass per-segment subtitleSegments[] (preferred) or one subtitleText. Each clip is transcribed: captions follow the real word timings, every clip is cut a quarter second after its last spoken word (never below 4 s), and audio is mastered to −14 LUFS with its true peak at −1 dBTP at most.

Request

{
  "sourceVideoUrls": ["https://… .mp4", "…"],   // 1–8, in order
  "burnSubtitles"?: boolean,
  "subtitleSegments"?: [{ "text", "durationSec", "style"?, "hookOverlay"? }],
  "subtitleText"?: "string",
  "upscaleTo"?: "1080p" | "4k" | "none",
  "callbackUrl"?: "https://…"
}

Response

{ "ok": true, "data": {
  "jobId": "uuid", "status": "queued",
  "statusUrl": "https://ppl.studio/api/v1/videos/assemble/{jobId}"
} }
GET/api/v1/videos/assemble/{id}API key

Poll an assemble job. The URLs fill in once status is done.

Response

{ "ok": true, "data": {
  "jobId", "status": "queued | running | done | failed",
  "combinedVideoUrl": "string | null", "subtitledVideoUrl": "string | null",
  "error": "string | null", "startedAt", "finishedAt"
} }
POST/api/v1/videos/upscaleAPI key

Re-scale any single video URL to 1080p, 2k or 4k (lanczos + sharpen) (202).

Request

{ "sourceVideoUrl": "https://… .mp4", "target"?: "1080p" | "2k" | "4k", "callbackUrl"?: "https://…" }

Response

{ "ok": true, "data": {
  "jobId": "uuid", "status": "queued",
  "statusUrl": "https://ppl.studio/api/v1/videos/upscale/{jobId}"
} }
GET/api/v1/videos/upscale/{id}API key

Poll an upscale job. videoUrl fills in once status is done.

Response

{ "ok": true, "data": {
  "jobId", "status": "queued | running | done | failed",
  "videoUrl": "string | null", "target": "1080p | 2k | 4k",
  "error": "string | null", "startedAt", "finishedAt"
} }

Music

Lyrics sung into a song — as a job; the result is a take in your gallery. Made on our side, free within a weekly allowance per user (429 past it).

POST/api/v1/songsAPI key

Sing lyrics into a song (201). Poll GET /api/v1/songs/{id}.

lyrics — a line per sung line, [Verse] / [Chorus] / [Bridge] on their own lines (or a blank line between verses) — in a genre (rnb, country, pop-ballad, soul, acoustic, upbeat-pop, hip-hop) or your own style, with an optional singer. The model's padded intro and outro are cut, and each line is found in the song (the words from your lyrics, the times from Whisper). Takes 2–5 minutes. To have the lyrics written, start the write / song brick (POST /api/v1/bricks/jobs) with a type — anthem, jingle (needs productName), list-song or drama-vsl — and a topic; its output carries lyrics, singer and genre to sing here.

Request

{ "lyrics": "[Verse]\nSaturday cookout…", "genre"?: "rnb", "style"?: "string", "singer"?: "string" }

Response

{ "ok": true, "data": { "id": "uuid", "kind": "song" } }
GET/api/v1/songs/{id}API key

Poll a song. song fills in once status is done.

Response

{ "ok": true, "data": {
  "id", "kind": "song", "status": "queued | running | waiting | done | failed | cancelled",
  "progress", "error",
  "song": { "assetId", "url", "seconds", "model",
            "lines": ["…"], "slots": [{ "start", "end" }], "words": [{ "line", "text", "start", "end" }],
            "found": 0.93, "trimmed": { "from", "to", "of" } | null } | null
} }
GET/api/v1/songsAPI key

The genres and the weekly allowance (seconds).

Response

{ "ok": true, "data": { "genres": [{ "id", "label" }], "weeklySeconds": 1200 } }

Social

Post finished gallery videos to your connected Facebook Pages and Instagram accounts, now or on a schedule. Connecting an account is an OAuth redirect in a signed-in browser — it can't be done with a key.

GET/api/v1/social/connectionsAPI key

Your connected accounts (never a token), and the URLs that connect or reconnect one in the browser.

Response

{ "ok": true, "data": {
  "connections": [{ "id", "platform": "facebook | instagram", "account_id", "display_name", "avatar_url",
                    "status": "active | needs_reauth", "last_error", "granted_scopes", "created_at", "updated_at" }],
  "facebookConfigured": true, "connectUrl", "reconnectUrl"
} }
DELETE/api/v1/social/connections/{id}API key

Disconnect an account — its token and share log go with it. Idempotent.

Response

{ "ok": true, "data": { "disconnected": true } }
POST/api/v1/social/facebook/shareAPI key

Share a gallery video to a connected Facebook Page as a Reel or video — published, or parked as a draft (201).

Request

{
  "connectionId": "uuid", "source": "videos | mascot_videos", "sourceId": "uuid",
  "format": "reel | video", "publishMode"?: "publish | draft",
  "message": "caption (may be empty)", "link"?: "https://…", "linkCta"?: "Learn more"
}

Response

{ "ok": true, "data": { "id", "platform", "format", "publish_mode", "status": "processing", "post_url",
  "error", "destination", "created_at", "link", "comment_id", "comment_error" } }
Meta transcodes after the upload — poll GET /api/v1/social/posts/{id} until status leaves processing. A published share gets the link as its first comment once live. 503 when the server has no Facebook app configured.
GET/api/v1/social/postsAPI key

Share history per gallery video, newest first. ?sourceId= narrows to one video.

Response

{ "ok": true, "data": { "sharesByVideoId": { "<sourceId>": [{ "id", "status": "processing | published | draft | failed", … }] } } }
GET/api/v1/social/posts/{id}API key

One share. While processing it asks Meta where it stands and records the outcome — poll every few seconds.

Response

{ "ok": true, "data": { "id", "status": "processing | published | draft | failed", "post_url", "comment_id", … } }
POST/api/v1/social/scheduledAPI key

Schedule a gallery video to post later (201) — 1 minute to 90 days ahead. Instagram connections only for now (400 otherwise).

Request

{
  "connectionId": "uuid", "source": "videos | mascot_videos", "sourceId": "uuid",
  "publishAt": "ISO date-time", "caption"?, "link"?, "linkCta"?
}

Response

{ "ok": true, "data": { "id", "platform", "status": "scheduled", "publishAt", "caption", "destination",
  "sourceTable", "sourceId", "lastError", "publishedAt", "postUrl" } }
GET/api/v1/social/scheduledAPI key

Your scheduled posts, soonest first (at most 200), including sent, failed and cancelled ones.

Response

{ "ok": true, "data": { "posts": [{ "id", "status": "scheduled | publishing | published | failed | cancelled", … }] } }
DELETE/api/v1/social/scheduled/{id}API key

Cancel a post that is still scheduled (400 once publishing has started).

Response

{ "ok": true, "data": { "cancelled": true } }

Free tools

Anonymous, rate-limited per IP — a minimum interval between calls (30–60 s) plus a daily cap (1–30/day), tuned per tool. JSON in, JSON out, no envelope, no key.

POST/api/tools/winning-ads-finder/generatePublic

Research live competitor ads in Meta Ad Library.

Request

{ "query": "string (brand or niche)", "type": "brand" | "niche" }

Response

{
  "ads": [{ "brand", "format", "hook", "body", "whyItWorks", "stealAngle" }],
  "adLibraryUrl": "string"
}
POST/api/tools/url-to-ad/generatePublic

Scrape a product URL, return 3 ad concepts.

Request

{ "url": "string (product PDP URL)" }

Response

{ "concepts": [{ "hook", "body", "cta", "visualDirection" }] }
POST/api/tools/hook-generator/generatePublic

Up to 30 hooks on measured opening patterns, for where the hook goes.

Request

{
  "about": "string (product or topic)",
  "isProduct": "boolean (default true)",
  "format": "spoken | overlay | cover | chat | post (default 'spoken')",
  "audience": "string (optional)",
  "platform": "TikTok | Instagram Reels | YouTube Shorts | Facebook / Meta ads | X / Threads | LinkedIn",
  "goal": "Views | Sales | Follows | Comments",
  "tone": "Casual | Warm | Funny | Deadpan | Edgy | Bold | Professional",
  "language": "English | Spanish | Portuguese | French | German | Italian | Dutch | Polish | Ukrainian | Turkish | Indonesian | Japanese",
  "patterns": "string[] (up to 6 hook pattern ids; default the format's first 4)",
  "perPattern": "3 | 5 (default 5)",
  "avoid": "string (comma-separated words to keep out)"
}

Response

{
  "hooks": [{
    "pattern",
    "line",
    "onScreenText (spoken)",
    "firstBubble (chat)",
    "openingVisual (spoken, overlay, cover)"
  }]
}
POST/api/tools/ugc-script-generator/generatePublic

Full 30s or 60s UGC script.

Request

{
  "product": "string",
  "audience": "string",
  "angle": "Problem-Solution | Transformation | Founder Story | Comparison | Unboxing/Demo",
  "length": "30s | 60s",
  "platform": "TikTok | Instagram Reels | YouTube Shorts | Meta Feed"
}

Response

{
  "script": {
    "hook",
    "beats": [{ "timestamp", "narration", "onScreenText", "shot", "broll" }],
    "cta"
  }
}
POST/api/tools/photo-prompt-generator/generatePublic

Optimized Gemini / Nano Banana image prompt.

Request

{
  "productDescription": "string",
  "category": "beauty | skincare | fashion | food | tech | home | fitness | other",
  "scene": "lifestyle | studio | outdoor | ...",
  "persona": "string (descriptor)"
}

Response

{ "prompt": "string (copy-paste ready)" }
POST/api/tools/randomizer/generatePublic

Anonymous one-shot UGC photo. Consumes an anonymous slot per IP.

multipart/form-data — a product image plus the same fields as the dashboard photo generator.

Response

{ "success": true, "imageUrl": "string" }
POST/api/tools/headline-tester/generatePublic

Score a headline (clarity / specificity / emotion) and return stronger variants.

Request

{ "headline": "string", "product": "string", "audience": "string" }

Response

{
  "score": { "clarity", "specificity", "emotion", "overall", "diagnosis" },
  "variants": [{ "headline", "angle", "whyItWorks" }]
}
POST/api/tools/email-subject-line-generator/generatePublic

Subject lines + preview text for an email type.

Request

{ "emailType": "string", "offer": "string", "audience": "string", "tone": "string" }

Response

{ "subjects": [{ "subject", "preview" }] }
POST/api/tools/aov-booster-generator/generatePublic

Average-order-value tactics with copy snippets and expected lift.

Request

{
  "product": "string",
  "currentAov": "string",
  "targetAov": "string",
  "audience": "string",
  "blockers": "string"
}

Response

{
  "tactics": [{ "category", "name", "description", "copySnippet", "expectedLift", "setupNotes" }]
}
POST/api/tools/black-friday-promo-generator/generatePublic

Black Friday promo concepts — mechanic, headline, scarcity copy, email subject.

Request

{
  "brand": "string",
  "product": "string",
  "audience": "string",
  "aov": "string",
  "margin": "string",
  "tone": "string"
}

Response

{
  "promos": [{ "mechanic", "headline", "discountSummary", "scarcityCopy", "emailSubject", "notes" }]
}
POST/api/tools/creator-pitch-email-generator/generatePublic

Brand-partnership pitch email for a creator, with subject options and a follow-up.

Request

{
  "brand": "string",
  "brandWhy": "string",
  "yourName": "string",
  "portfolio": "string",
  "niche": "string",
  "proof": "string",
  "ask": "string"
}

Response

{ "subjectOptions": ["string"], "body": "string", "followUp": "string", "notes": ["string"] }