---
title: "Preview Cpp Set"
method: POST
path: "/v1/apps/{listing_id}/cpp-sets/preview"
tags: ["creative-apps"]
---

# Preview Cpp Set

`POST /v1/apps/{listing_id}/cpp-sets/preview`

## Request

- Base URL: `https://api.theagentc.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.theagentc.io/v1/apps/{listing_id}/cpp-sets/preview`
- Auth: HTTP bearer

Free, fast, live preview of the CPP screenshot-set builder: renders the
REAL pipeline at 25% scale (or `scale` if given) so the builder UI can
show a live view as the user tweaks layout/headlines/theme.

Two response shapes, selected by `body.slide`:
  - `slide` omitted/null: the full-strip render — one composited strip of
    all 6 slides (for the filmstrip rail).
  - `slide` set (0-5): the focused-slide fast path — same render (the
    full 6-slide canvas is still composited; cross-slide device bleed
    means a slide can't render in isolation) but the response encodes
    and returns ONLY that one slide's image, and `slides_meta` carries
    just that slide's regions in image-local coordinates. This is the
    hot interactive path for a focused-slide edit loop, so it's
    rate-limited on its own, more generous window
    (creative_preview.PREVIEW_SLIDE_RATE_LIMIT_PER_MIN) rather than
    sharing the full-strip budget.

No credit check or deduction, no CreativeBatch/Job/CreativeAsset rows, and
no vision calls (geometric placement only) — true for both response
shapes. Serialized per workspace (one render in flight at a time)
regardless of `slide`.

## Path parameters

- `listing_id` string, uuid, required

## Request body

- CppSetPreviewRequest: Free, fast, low-res live preview of the CPP set builder — no credits, no persisted rows, no vision calls. Mirrors CppSetCreate's shape for the fields the preview actually varies. `slide`: when set, this is a FOCUSED-SLIDE refresh — the render still composites the full 6-slide canvas (cross-slide device bleed means a single slide can't be rendered in isolation: bridge/tilted devices on slide i can paint into slide i+1's crop region — see creative_render.render_panoramic_slides), but the response encodes and returns ONLY that one slide's image instead of the full 6-up strip. This is the hot interactive path (every headline/layout tweak while a slide is focused) — see CppSetPreviewResponse.slide / .slides_meta for the single-slide response contract, and creative_preview's PREVIEW_SLIDE_RATE_LIMIT_PER_MIN for its more generous rate-limit window. Omit (null) for the normal full-strip render (all 6 slides, used for the filmstrip rail). `scale`: optional render scale, clamped to {0.25, 0.4}. Default 0.25 (330x717 @ 69"). 0.4 (528x1147 @ 69") renders a crisper focused slide — intended for use together with `slide`, though it's accepted either way.
  - `device` string
  - `layout` string
  - `theme_prompt` string, nullable
  - `theme_image_key` string, nullable
  - `slides` CppSlide[], nullable
    - `shot` integer, nullable
    - `headline` string
    - `focus` string, nullable
    - `region` SlideRegionRect: An explicit rect override, floats 0-1 in SCREENSHOT fractions (the RAW screenshot's own width/height — the same coordinate space screenshot_regions.RegionHit.bbox uses). x0<x1, y0<y1 required; a degenerate box (too thin/short to be a legible region) is rejected rather than silently clamped. v1 non-editable-on-tilted-slides caveat: for a TILTED slide (the classic/momentum 45°-bridge hero, or zoom's rotated bookend devices at slides 0/5), the render pipeline's recorded `screen_rect` is only the post-rotation `expand=True` device bbox — an axis-aligned box 1.65-2.25x larger than the phone's actual visible screen, with no inverse-rotation math to map a Studio drag back to a true screenshot fraction. Posting a `region`/`chip_regions` override for a slide that turns out to be tilted is still accepted (the backend never 4xx's on it), but the render pass reports every region on that slide as `editable: false` in `slides_meta` (see SlideMeta/SlideRegionMeta below) so the Studio region editor never offers drag handles there, instead of silently round-tripping a user's box to the wrong place. This may be revisited with real rotation-aware mapping in a later version.
      - `x0` number, required
      - `y0` number, required
      - `x1` number, required
      - `y1` number, required
    - `chip_regions` ChipRegion[], nullable
      - `x0` number, required
      - `y0` number, required
      - `x1` number, required
      - `y1` number, required
      - `label` string, nullable
  - `slide` integer, nullable
  - `scale` number, nullable

## Response `200`

Successful Response

- CppSetPreviewResponse
  - `strip` string, required
  - `slide_w` integer, required
  - `slide_h` integer, required
  - `theme_image_key` string, nullable
  - `scene_status` string, nullable
  - `slides_meta` SlideMeta[], nullable
    - `slide` integer, required
    - `screen_rect` number[], nullable
    - `regions` SlideRegionMeta[]
      - `kind` string, required
      - `idx` integer, required
      - `rect` number[], required
      - `editable` boolean
  - `slide` integer, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/theagentc/apis/the-agent-c-api.md) · [All operations](https://skmtc.dev/theagentc/apis/the-agent-c-api/llms.txt) · [OpenAPI document](https://skmtc.dev/theagentc/apis/the-agent-c-api/revisions/1c9868b44584?raw)