API

Two on-ramps. One credit wallet.

Ounie accounts hit the REST endpoints with a bearer token. AI assistants — including the Ounie AI Team — connect over MCP and get a native tool surface. Both run the same generation pipeline, and every call draws your shared Ounie credits (1 credit = 1¢), never overdrawing. Generating a carousel is grounded in your private Ounie brain, so it uses your fleet master key — there is no keyless pay-per-call rail here.

MCP · for AI assistants and the Ounie AI Team

Streamable HTTP at /api/mcp (legacy SSE at /api/sse). Auth with a crs_live_… key from your dashboard, or the Ounie fleet master key ounie_live_… (required to generate — it grounds on your brain).

Endpoint  https://carousel.ounie.com/api/mcp
Header    Authorization: Bearer ounie_live_…

# If your MCP client can't set headers, append the key as a query param:
https://carousel.ounie.com/api/mcp?api_key=ounie_live_…

Tool	What it does	Cost
list_carousels	List your carousels (title, hook, theme, slide count, status).	free
get_carousel	Full copy + citations + per-slide PNG export URLs for one carousel.	free
list_themes	The theme catalog — built-ins plus your custom themes.	free
generate_carousel	Generate a cited carousel from your brain(s). Master key only.	10 credits
get_credit_balance	Spendable Ounie credits + monthly included.	free
get_pricing	Per-action pricing. No auth required.	public
whoami	The authenticated key's owner + key id.	free

Connect from the Ounie AI Team (TabTab): add an HTTP MCP server pointing at https://carousel.ounie.com/api/mcp?api_key=ounie_live_…. Its HTTP MCP entries can't set an Authorization header, so the key rides the URL.

REST · the same endpoints the dashboard uses

Send Authorization: Bearer crs_live_… (or ?api_key=) on any of these. Cookie sessions work too — it's the same route. Brain-grounded routes (create, brain picker) need the master key ounie_live_….

GET/api/carousels— List your carousels

Any key. Free.

POST/api/carousels— Generate a carousel

{ "brain_ids": ["…"], "topic": "launch week", "slide_count": 7, "theme": "ink" }

Bills 10 credits (settled only when a carousel is produced; thin material = no charge). Grounded + cited from your brains — needs a cookie session OR the master key (ounie_live_). A per-app crs_live_ key gets a 403 use_master_key.

GET/api/carousels/{id}— Detail + slides

Any key. Free. Returns the carousel row and its slides.

PATCH/api/carousels/{id}— Restyle theme

{ "theme": "sunset" }

Free — a theme switch restyles every downloaded slide.

PATCH/api/carousels/{id}/copy— Edit the words

{ "title": "…", "hook": "…", "cta": "…", "caption": "…", "hashtags": ["…"], "slides": [{ "id": "…", "title": "…", "body": "…" }] }

Free — text only. Your own edits; citations preserved as provenance.

POST/api/carousels/{id}/render— Design / render slides

{ "render_mode": "ai", "theme": "ink", "backdrop": false }

Bills the design work only: classic no-backdrop is free, AI backdrop 12 cr, AI-painted slides 12 cr each. Settles on artifacts that actually render.

GET/api/carousels/{id}/slides/{position}/image— Export a slide PNG

Any key. Free. Renders a 1080×1350 PNG. position 0 = cover/hook, 1..N = content, N+1 = CTA. Append ?api_key=crs_live_… to download.

GET/api/brains— Your brains (picker)

Master key or cookie only — reads your private brains upstream.

GET/api/themes— Theme catalog

Any key. Free. Built-ins + your custom themes.

DELETE/api/keys?id={id}— Revoke a key

Cookie only — mint/revoke keys from the dashboard.

Why no keyless (x402) rail?

Every carousel is written from your private Ounie brain.

Some Ounie apps offer keyless pay-per-call in USDC (x402). Carousel Studio does not: a carousel is only meaningful when it's grounded in a specific person's knowledge, so generation is always tied to an Ounie account and its brains. Agent access is by API key or MCP, billed in your shared Ounie credits.

Shape of a generated carousel

{
  "carousel_id": "…",
  "hook": "The cover-slide line, grounded in your brain.",
  "slides": [
    { "title": "…", "body": "…", "cited_from": "Source page title" }
  ],
  "cta": "…",
  "caption": "The post caption, ready to publish.",
  "hashtags": ["launch", "ai"],
  "export_slide_urls": [
    "https://carousel.ounie.com/api/carousels/…/slides/0/image"
  ],
  "credits_spent": 10,
  "thin_context": false
}