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.
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.
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.
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.
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 }'
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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).
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)"
}
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.
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.
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.
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.
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).
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).
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.
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.
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.
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.
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.
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.
Update a directory persona (partner key or owner).
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.
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.
Change name, own, platform, storeUrl, country, developer, genre, description, iconUrl, screenshots (the whole list, in order — reorder, caption, drop or add).
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.
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.
Add an already-hosted image URL to your gallery as it is (201) — no copy is made. To keep a copy of an image from any URL, POST /api/v1/uploads with { url, gallery: true }; for a local file, with gallery=true.
Everything the bricks made — briefs, scripts, takes, images, clips, cuts, slides — newest first, ready ones only.
Request
?kind=brief,script,take,image,clip,video,slides // comma-separated
&runId=uuid // one run's
&limit=50 // 1–200
&before=ISO time // pass nextBefore for the next page
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.
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.
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).
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.
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)"
}
What's trending right now, for a person picking a topic or a flow that runs by itself — TikTok's search lists and the searches rising on Google, a niche's own first.
From the trends library that ships with the app (what /topics shows). For a niche (a niche playbook id; all or none for every niche) its own topics come first — TikTok phrases and Google searches kept to the niche by meaning, rising then steady — then TikTok's general lists (niche: null). why says why in a few words; a search that jumped from nothing says it's rising, never a percentage. medium: carousel takes photo-post and list-shaped topics first, video/talking leave photo posts last. A topic whose TikTok search our research charted has a peak: its phase against its 6-month high (rising and near peak move up, peaked, falling and quiet move down, never out), the line behind it and the next peak when it's known. A search only a local business answers (… near me, hvac repair, landscaping company) and a cut-off related search (when the relationship) are never offered. Start one with POST /api/v1/flows and brief: { niche: title, nicheOverride: niche }.
Request
?niche=food-drink&medium=video&limit=20 // niche: a playbook id or all; medium: video | talking | carousel; limit 1-100 (20)
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.
The creators taking off in a niche on TikTok — accounts beating their own usual views, and TikTok One's creators beside the niche's trending hashtags.
From the same library (the Creators tab on /topics). breakout: accounts our research found with a post in the niche far above their usual views (bestMultiple is that post's views over their median; hot ones are doing it now and come first); formats are the library formats their posts were labelled as. tiktokOne: TikTok One's trending US hashtags in the niche, with the creators it shows beside each. Empty lists until the library has read them. Without a niche: every niche's counts.
Request
?niche=relationships&limit=15 // limit 1-15 (15), per list
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.
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).
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" }
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).
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
}
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.
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.
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.
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.
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.
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.
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.
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/flowsbody). 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.
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.
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.
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).
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.
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.
{ "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.
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.
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.
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?
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.
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.
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)
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.
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.
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.
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" }
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.
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.
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 } }
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.
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.filmedphone 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.shapewhat-is · how-to · how-it-works · vs · worth-it · alternatives · does-it-work · price · facts · for-who, options.styleanswer: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 }.
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).
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.
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 }.
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
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Your connected accounts (never a token), and the URLs that connect or reconnect one in the browser.
Response
Disconnect an account — its token and share log go with it. Idempotent.
Response
Share a gallery video to a connected Facebook Page as a Reel or video — published, or parked as a draft (201).
Request
Response
GET /api/v1/social/posts/{id}until status leavesprocessing. A published share gets the link as its first comment once live.503when the server has no Facebook app configured.Share history per gallery video, newest first. ?sourceId= narrows to one video.
Response
One share. While processing it asks Meta where it stands and records the outcome — poll every few seconds.
Response
Schedule a gallery video to post later (201) — 1 minute to 90 days ahead. Instagram connections only for now (400 otherwise).
Request
Response
Your scheduled posts, soonest first (at most 200), including sent, failed and cancelled ones.
Response
Cancel a post that is still scheduled (400 once publishing has started).
Response