render_strip

What it does

• Writes
• No account needed

The main event. Each screenshot is composited into a styled 3D device mockup, laid out as an App Store strip with the headlines you pass, and returned as one PNG per panel at the exact store panel size. Nothing is saved and no project is created; this call only renders, and the result says so — a render with no project carries an offer to save, not an instruction to. Start with a preview — it costs a quarter of a full-resolution render and is what you iterate against — and switch to full resolution once the composition is right.

You can ask: “Turn these imported Tidebook screenshots into a three-panel preview.”

The published schema deliberately accepts any shape inside screenshots so a malformed entry comes back as a sentence rather than a stacked union error. The real element shapes are below under what the server accepts.

Input

• screenshotsarrayrequiredat least 1 itemat most 10 items

  Screenshots in App Store display order (1–10). Preferred common form: a FLAT array, where each entry becomes its own App Store panel, e.g. [{ "ref": "first" }, { "ref": "second" }]. Advanced multi-phone form: a NESTED array of slots, where several entries inside one slot are composited into that single panel, e.g. [[{ "ref": "left" }, { "ref": "right" }], [{ "ref": "third" }]]. Each screenshot entry is EITHER an inline base64 PNG string (capped at 3MB of image data — a full-resolution screenshot is 3-4MB and will NOT fit; use a ref for anything real), OR { "ref": "..." } from request_screenshot_upload, OR { "url": "https://..." }, OR (local stdio mode only) { "path": "/abs/or/relative/path.png" } to read a file straight off disk, OR { "locales": { "<locale>": <any of those> } } to vary that screenshot per App Store locale (missing locales fall back to the en-US variant). Prefer ref/url for real screenshots so the bytes never transit this conversation.

  each item

  any

  The published schema does not constrain this element, on purpose — a malformed entry comes back as a sentence instead of a stacked union error. What the server re-validates against is below.

• panelPresetIdstringoptional

  App Store screenshot size. Default r69 (6.9″ iPhone, 1290×2796). iPhone sizes only — iPad is not rendered yet.

  one ofr69r65r55

• clipstringoptional

  An explicit top-level clip: "strip" or clip: "panel" wins over every shot; "strip" forces continuous overflow and "panel" clips every device to its own panel. Omit clip to honour each shot's clipToFrame; when it is missing or false, overflow is allowed.

  one ofstrippanel

• lookobjectoptional

  A ShotOps "look" — per-DEVICE styling + background, exactly as read_look returns it. Its shots[] give every screenshot/phone its own styling (including multiple phones in one panel); style.shotLook is one shared style for all. COMPOSES with style: pass a look for the devices + style.captions for the words in ONE render. Validated — unknown keys are rejected (call describe_look for the full field catalog).

  • schemanumberoptional

    Look schema version. The server stamps it on every save (save_look); read_look returns it. Any input value is ignored — never set it yourself.

  • panelPresetIdstringoptional

    Canvas size preset, e.g. r69 = 1290×2796. Default r69.

  • bgModestringoptional

    One gradient across the strip, or a flat colour per panel. Default gradient.

    one ofgradientperPanel

  • gradientStopsarrayoptionalat least 1 item

    Canonical gradient stops — { color (hex), at (0–1 position) } — wins over gradientFrom/gradientTo/gradientDir when present. Read this back for the full stop list a Studio-authored look may carry; the trio below is only ever a two-stop summary.

    each item

    object

    • colorstringrequired

    • atnumberrequiredmin 0max 1

  • gradientAnglenumberoptional

    Canonical gradient angle in degrees, clockwise from "to top" (CSS convention: 90 = right, 180 = down, the gradientDir:"vertical" equivalent). Paired with gradientStops.

  • gradientFromstringoptional

    Gradient start (hex) — a DERIVED mirror of gradientStops[0], re-derived from the stops on every render and reload. Setting it ALONE changes nothing: set gradientStops to change the backdrop. Default #1b1b2e.

  • gradientTostringoptional

    Gradient end (hex) — a DERIVED mirror of the last gradientStops entry, re-derived from the stops on every render and reload. Setting it ALONE changes nothing: set gradientStops to change the backdrop. Default #0a0a14.

  • gradientDirstringoptional

    A DERIVED mirror of gradientAngle (nearest axis), re-derived on every render and reload. Setting it ALONE changes nothing: set gradientAngle to turn the gradient. Default vertical.

    one ofhorizontalvertical

  • panelColorsobjectoptional

    Per-panel flat colours (mode perPanel), keyed by panel id.

  • shadowbooleanoptional

    Drop shadow under the phones. Default true.

  • floorReflectionbooleanoptional

    Flipped, faded floor reflection under each phone. Default false.

  • panelBackgroundsobjectoptional

    Per-frame background overrides keyed by panel id (web-authored; agents rarely set these).

  • captionStylesobjectoptional

    Per-panel caption STYLE arrays keyed by panel id (styling only, no words — for caption text pass style.captions).

  • shotsarrayoptionalat most 60 items

    One entry per SCREENSHOT/DEVICE, flattened in panel order. Each entry has its OWN look. For screenshots:[[left,right]], pass two shots with the SAME panelId ("panel-1") to give the two devices different colours/materials/angles. This is how a look varies devices; style.shotLook cannot.

    each item

    object

    • panelIdstringoptional

      Panel containing this screenshot/device. Panels are panel-1…panel-N in slot order; REPEAT the same panelId for multiple devices in one panel. A saved look’s own ids are remapped by ordinal.

    • lookobjectoptional

      This individual screenshot/device’s styling — the SAME fields as style.shotLook.

      • anglestringoptional

        Camera preset. Default front.

        one offrontleftright

      • cameraPosone of 2 shapesoptional

        Manual camera position override; null/omit = use the angle preset.

        1x

        • xnumberrequired

        • ynumberrequired

        • znumberrequired

        2null

      • rollstring or numberoptional

        -45–45° clock-hand tilt. Default 0.

      • phoneHeightstring or numberoptional

        -45–45° clock-hand tilt. Default 0.

      • hOffsetstring or numberoptional

        -45–45° clock-hand tilt. Default 0.

      • vOffsetstring or numberoptional

        -45–45° clock-hand tilt. Default 0.

      • materialstringoptional

        Device body. Default real.

        one ofrealclay

      • colorwaystringoptional

        Body colour (material "real"). Default silver. These are finish SLOTS — each device binds its own real finish (silver = iPhone Silver / Pixel Moonstone). "green" is Pixel-only (Jade); other devices fall back to their first finish.

        one oforangebluesilvergreencustom

      • customColorstringoptional

        Hex body colour when colorway is "custom".

      • finishstring or numberoptional

        -45–45° clock-hand tilt. Default 0.

      • clearcoatstring or numberoptional

        -45–45° clock-hand tilt. Default 0.

      • clayTonestringoptional

        Clay tone (material "clay"). Default grey.

        one ofgreywhitecharcoalcustom

      • clayCustomstringoptional

        Hex clay colour when clayTone is "custom".

      • flatScreenbooleanoptional

        Render the screen flat (no curvature). Default false.

      • glarebooleanoptional

        Screen glare. Default false.

      • lightingbooleanoptional

        Scene lighting. Default true.

      • reflectionsbooleanoptional

        Body reflections. Default false.

      • clipToFramebooleanoptional

        Clip this complete device composite to its owning frame. Default false (overflow allowed).

• styleobjectoptional

  Structured styling — the discoverable path (call describe_look for the full field catalog + defaults). layout is the fastest way in: one named composition that settles the headline region and the device placement together, with your explicit fields still winning over it. COMPOSES with look: pass BOTH to get per-device styling from the look AND captions from style.captions in ONE render (every real App Store strip). When a look is also given it supplies the devices + background, so style.shotLook/style.background are ignored (a note says so) — use style for captions then. Alone, style styles every phone identically + captions. Also composes with useSavedLook/version.

  • layoutstringoptional

    Panel COMPOSITION template — sets the headline’s reserved region and the device’s placement, camera pose, and roll in one choice. "standard" — Headline on top, whole device below it, nothing cropped. The safe default. Reserves 2 headline lines (~36 characters). Character: [safe]. "bleed" — Room for a longer headline, device running off the bottom edge. What the market looks like. Reserves 4 headline lines (~72 characters). Character: [conventional]. "top-bleed" — Device running off the TOP edge, headline underneath it. Inverts the usual reading order. Reserves 4 headline lines (~72 characters). Character: [expressive]. PRECEDENCE: the template expands FIRST into shotLook.phoneHeight/shotLook.hOffset/shotLook.vOffset/shotLook.angle/shotLook.cameraPos/shotLook.roll and captions[].sizePt/captions[].maxWidth/captions[].reserveLines/captions[].band, and THEN any of those fields you pass EXPLICITLY overrides it — so { layout: "bleed", shotLook: { vOffset: "45" } } renders bleed seated at 45, not at the template’s 38. That is how you say "bleed, but a bit lower" without the template silently winning. The reserved region is held at FULL SIZE whether or not the headline fills it, which is what makes every panel in a swiped set land on the same line. Nothing stores the template id: it is discarded at expansion, so a saved project and read_look carry only the expanded values.

    one ofstandardbleedtop-bleed

  • shotLookobjectoptional

    This individual screenshot/device’s styling — the SAME fields as style.shotLook.

    • anglestringoptional

      Camera preset. Default front.

      one offrontleftright

    • cameraPosone of 2 shapesoptional

      Manual camera position override; null/omit = use the angle preset.

      1x

      • xnumberrequired

      • ynumberrequired

      • znumberrequired

      2null

    • rollstring or numberoptional

      -45–45° clock-hand tilt. Default 0.

    • phoneHeightstring or numberoptional

      -45–45° clock-hand tilt. Default 0.

    • hOffsetstring or numberoptional

      -45–45° clock-hand tilt. Default 0.

    • vOffsetstring or numberoptional

      -45–45° clock-hand tilt. Default 0.

    • materialstringoptional

      Device body. Default real.

      one ofrealclay

    • colorwaystringoptional

      Body colour (material "real"). Default silver. These are finish SLOTS — each device binds its own real finish (silver = iPhone Silver / Pixel Moonstone). "green" is Pixel-only (Jade); other devices fall back to their first finish.

      one oforangebluesilvergreencustom

    • customColorstringoptional

      Hex body colour when colorway is "custom".

    • finishstring or numberoptional

      -45–45° clock-hand tilt. Default 0.

    • clearcoatstring or numberoptional

      -45–45° clock-hand tilt. Default 0.

    • clayTonestringoptional

      Clay tone (material "clay"). Default grey.

      one ofgreywhitecharcoalcustom

    • clayCustomstringoptional

      Hex clay colour when clayTone is "custom".

    • flatScreenbooleanoptional

      Render the screen flat (no curvature). Default false.

    • glarebooleanoptional

      Screen glare. Default false.

    • lightingbooleanoptional

      Scene lighting. Default true.

    • reflectionsbooleanoptional

      Body reflections. Default false.

    • clipToFramebooleanoptional

      Clip this complete device composite to its owning frame. Default false (overflow allowed).

  • backgroundobjectoptional

    • modestringoptional

      One gradient across the strip, or a flat colour per panel.

      one ofgradientperPanel

    • stopsarrayoptionalat least 1 item

      Gradient colour stops, in order along the gradient line — { color (hex), at (0–1 position; 0 = line start, 1 = line end) }. Two stops is the classic top/bottom gradient, more make a multi-colour sweep, one stop is a solid fill. Default a two-stop navy gradient: [{color:"#1b1b2e",at:0},{color:"#0a0a14",at:1}].

      each item

      object

      • colorstringrequired

      • atnumberrequiredmin 0max 1

    • anglenumberoptional

      Gradient angle in degrees, clockwise from "to top" — CSS linear-gradient() convention: 90 = to right, 180 = to bottom (the old "vertical" default, and this field’s own default), 270 = to left. Any value folds into 0–360.

    • panelColorsarrayoptionalat most 10 items

      Per-panel flat colours (mode "perPanel"), one entry per slot in order; null = default.

      each item

      string or null

    • shadowbooleanoptional

      Drop shadow under the phones. Default true.

    • floorReflectionbooleanoptional

      Flipped, faded floor reflection under each phone. Default false.

  • captionsarrayoptionalat most 10 items

    One entry PER PANEL in slot order; null = no caption on that panel. An entry is EITHER a single caption object OR an array of caption layers (stacked, in order) on that panel. Alongside a look, an entry is a DELTA: every style field you set wins, every field you leave out keeps the look’s styling for that panel and layer — which is what lets you re-render a layout.correctedLook without restating your captions.

    each item

    one of 2 shapes

    1one of 2 shapes

    1object

    • fontIdstringoptional

      Bundled font. Default inter.

      one ofintermanropepoppinsfrauncesspace-grotesk

    • sizePtnumberoptionalgreater than 0

      Font size in iOS points (preset-independent), 20–120. Default 32. Outside that range it is clamped to it and the response says so.

    • colorstringoptional

      Text colour (hex). Default FFFFFF.

    • alignstringoptional

      Default center.

      one ofleftcenterright

    • anchorobjectoptional

      Normalized 0–1 position of the caption on the panel. Default {x:0.5, y:0.06}.

      • xnumberoptionalmin 0max 1

      • ynumberoptionalmin 0max 1

    • maxWidthnumberoptionalgreater than 0

      Wrap width as a fraction of the panel, 0.1–1. Default 0.86. Outside that range it is clamped to it and the response says so.

    • reserveLinesintegeroptionalmin 1max 8

      How many lines of headline room to HOLD, whether or not the text fills it. A shorter headline is centred in the reserved space rather than leaving all the slack beneath it, and the space is held so every panel in the strip lands on the same line. Omit to let the caption be exactly as tall as its text. Set for you by style.layout.

    • bandstringoptional

      Put this caption in the BOTTOM band, growing upward from the lower margin, instead of the default top band. This is how a headline sits UNDER the device (see the top-bleed layout). The caption stays auto-placed — it still reflows and still stacks; use this rather than pinning an anchor, which would freeze it.

      one ofbottom

    • bandInsetnumberoptionalmin 0max 0.5

      Inset of the auto caption band from its own panel edge, as a 0–0.5 fraction of panel height. The top band measures down; the bottom band mirrors it upward. Default 0.06.

    • lineHeightnumberoptionalmin 0.5max 3

      Line spacing as a multiple of font size, 0.5–3. Default 1.2.

    • bandCenternumberoptionalmin 0max 1

      Horizontal reference of the auto caption block as a 0–1 fraction of panel width. Text alignment decides which edge sits there. Default 0.5.

    • textstringoptionalat most 200 characters

      The headline — per-RENDER input, never stored in a look.

    • subtitlestringoptionalat most 300 characters

      Optional subtitle under the headline — also per-render input.

    2array

    each item

    object

    • fontIdstringoptional

      Bundled font. Default inter.

      one ofintermanropepoppinsfrauncesspace-grotesk

    • sizePtnumberoptionalgreater than 0

      Font size in iOS points (preset-independent), 20–120. Default 32. Outside that range it is clamped to it and the response says so.

    • colorstringoptional

      Text colour (hex). Default FFFFFF.

    • alignstringoptional

      Default center.

      one ofleftcenterright

    • anchorobjectoptional

      Normalized 0–1 position of the caption on the panel. Default {x:0.5, y:0.06}.

      • xnumberoptionalmin 0max 1

      • ynumberoptionalmin 0max 1

    • maxWidthnumberoptionalgreater than 0

      Wrap width as a fraction of the panel, 0.1–1. Default 0.86. Outside that range it is clamped to it and the response says so.

    • reserveLinesintegeroptionalmin 1max 8

      How many lines of headline room to HOLD, whether or not the text fills it. A shorter headline is centred in the reserved space rather than leaving all the slack beneath it, and the space is held so every panel in the strip lands on the same line. Omit to let the caption be exactly as tall as its text. Set for you by style.layout.

    • bandstringoptional

      Put this caption in the BOTTOM band, growing upward from the lower margin, instead of the default top band. This is how a headline sits UNDER the device (see the top-bleed layout). The caption stays auto-placed — it still reflows and still stacks; use this rather than pinning an anchor, which would freeze it.

      one ofbottom

    • bandInsetnumberoptionalmin 0max 0.5

      Inset of the auto caption band from its own panel edge, as a 0–0.5 fraction of panel height. The top band measures down; the bottom band mirrors it upward. Default 0.06.

    • lineHeightnumberoptionalmin 0.5max 3

      Line spacing as a multiple of font size, 0.5–3. Default 1.2.

    • bandCenternumberoptionalmin 0max 1

      Horizontal reference of the auto caption block as a 0–1 fraction of panel width. Text alignment decides which edge sits there. Default 0.5.

    • textstringoptionalat most 200 characters

      The headline — per-RENDER input, never stored in a look.

    • subtitlestringoptionalat most 300 characters

      Optional subtitle under the headline — also per-render input.

    2null

• useSavedLookbooleanoptional

  If true, style the strip with the project's saved look (ignored when look/style is given).

• projectstringoptionalat least 1 character

  Which ShotOps project to target: its id (as returned by read_look/save_project), OR its NAME as the user says it — matched exactly, ignoring case and surrounding spaces. Omit = your most recently edited project. A name that matches none or several is refused with the account's projects listed, never resolved by guessing.

• versionintegeroptionalmin 1

  Render a specific saved look version of the project (implies the saved look). Omit = the project's HELD version if one is held (hold_look), else the latest saved look.

• localestringoptional

  App Store locale, e.g. "de-DE" (default en-US). Labels the render, selects which { "locales": … } screenshot variants render, and, for emit_bundle, selects the fastlane screenshots folder. Does not select caption text — pass the copy for this locale yourself via style.captions[].text (see the README's captions.<locale>.json convention).

• previewbooleanoptional

  Render at ~25% resolution for a fast styling preview at a quarter the render cost — small enough to always come back inline. Not for final delivery: re-render without preview (or use emit_bundle directly) once the look is right.

• outputstringoptional

  How to return rendered bytes: "inline" (base64), "urls" (uploaded, short-lived signed download URLs — use for real/full-resolution renders so bytes never transit this conversation), or omit for auto (inline under ~200KB total, urls above).

  one ofinlineurls

• waiversarrayoptional

  Approvals for readiness findings this run would otherwise be blocked on. Pass back the exact contract.readiness.findings[] id and digest from a preview: true run, or from the refusal you just received. Each waiver clears ONE finding; fatal findings are never waivable.

  each item

  object

  • findingIdstringrequired

    The contract.readiness.findings[].id this waiver authorizes. Exactly one.

  • findingDigeststringrequired

    That finding’s digest. A digest from an earlier run no longer matches and is rejected as stale.

  • policyVersionstringrequired

    contract.readiness.policyVersion as it stood when the finding was raised.

  • waivedBystringrequired

    The account that approved it. Must be the account making this call.

  • waivedAtstringrequired

    ISO 8601.

  • reasonstringoptional

    Free text, for the receipt. It authorizes nothing on its own.

• idempotencyKeystringoptionalat least 1 characterat most 200 characters

  Stable retry key for paid Hosted production. Reuse it only for the identical request; a new key deliberately requests a new render. Omit it for deterministic fingerprint retry safety.

What the server actually accepts

The published schema above deliberately accepts a wider shape for screenshots, so a malformed entry comes back as a sentence rather than a stack of union errors. The server re-validates against these shapes and refuses anything else.

• screenshotsone of 2 shapesrequired

  Screenshots in App Store display order (1–10). Preferred common form: a FLAT array, where each entry becomes its own App Store panel, e.g. [{ "ref": "first" }, { "ref": "second" }]. Advanced multi-phone form: a NESTED array of slots, where several entries inside one slot are composited into that single panel, e.g. [[{ "ref": "left" }, { "ref": "right" }], [{ "ref": "third" }]]. Each screenshot entry is EITHER an inline base64 PNG string (capped at 3MB of image data — a full-resolution screenshot is 3-4MB and will NOT fit; use a ref for anything real), OR { "ref": "..." } from request_screenshot_upload, OR { "url": "https://..." }, OR (local stdio mode only) { "path": "/abs/or/relative/path.png" } to read a file straight off disk, OR { "locales": { "<locale>": <any of those> } } to vary that screenshot per App Store locale (missing locales fall back to the en-US variant). Prefer ref/url for real screenshots so the bytes never transit this conversation.

  1array

  Preferred: one screenshot entry per App Store panel, in display order.

  each item

  one of 5 shapes

  1string

  Inline base64-encoded PNG (no "data:" prefix). Capped at 3MB of image data — a real full-resolution screenshot is 3-4MB and will NOT fit. Use request_screenshot_upload and pass { ref } instead; inline is for thumbnails and tests.

  2ref

  A ref returned by request_screenshot_upload — resolved server-side, never re-sent inline.

  • refstringrequiredat least 1 character

  • namestringoptionalat most 200 characters

    The screenshot's original filename (e.g. "03_statistics.png"). Pass it so that, if this render is saved as a project, the user's own screenshots folder re-loads exactly this file by name. Optional if the ref already carries a name (from request_screenshot_upload({ names })); omit entirely and the record falls back to a positional name (screen-N.png).

  3url

  An https URL to a PNG or JPEG — fetched server-side, converted to PNG when needed (no redirects, ~20MB cap).

  • urlstringrequiredat least 1 character

  • namestringoptionalat most 200 characters

    The screenshot's original filename (e.g. "03_statistics.png"). Pass it so that, if this render is saved as a project, the user's own screenshots folder re-loads exactly this file by name. Optional if the ref already carries a name (from request_screenshot_upload({ names })); omit entirely and the record falls back to a positional name (screen-N.png).

  4path

  A local filesystem path to a PNG, read straight off disk — ONLY available over the local stdio server (npx shotops-mcp); the hosted server rejects this entry shape.

  • pathstringrequiredat least 1 character

  • namestringoptionalat most 200 characters

    The screenshot's original filename (e.g. "03_statistics.png"). Pass it so that, if this render is saved as a project, the user's own screenshots folder re-loads exactly this file by name. Optional if the ref already carries a name (from request_screenshot_upload({ names })); omit entirely and the record falls back to a positional name (screen-N.png).

  5locales

  Per-locale variants of ONE screenshot: { "locales": { "en-US": <entry>, "de-DE": <entry> } } (each variant is an inline base64 / ref / url / path entry). render_strip picks the top-level locale's variant; emit_bundle with locales renders/packages every listed locale. A locale with no variant of its own falls back to the en-US variant (else the first declared), so you can localize only some screenshots.

  • localesobjectrequired

  2array

  Advanced: one nested slot per panel; put several screenshot entries in a slot for a multi-phone panel.

  each item

  array

  One App Store slot: 1–6 screenshots. Several entries = several phones composited into that one slot.

  each item

  one of 5 shapes

  1string

  Inline base64-encoded PNG (no "data:" prefix). Capped at 3MB of image data — a real full-resolution screenshot is 3-4MB and will NOT fit. Use request_screenshot_upload and pass { ref } instead; inline is for thumbnails and tests.

  2ref

  A ref returned by request_screenshot_upload — resolved server-side, never re-sent inline.

  • refstringrequiredat least 1 character

  • namestringoptionalat most 200 characters

    The screenshot's original filename (e.g. "03_statistics.png"). Pass it so that, if this render is saved as a project, the user's own screenshots folder re-loads exactly this file by name. Optional if the ref already carries a name (from request_screenshot_upload({ names })); omit entirely and the record falls back to a positional name (screen-N.png).

  3url

  An https URL to a PNG or JPEG — fetched server-side, converted to PNG when needed (no redirects, ~20MB cap).

  • urlstringrequiredat least 1 character

  • namestringoptionalat most 200 characters

    The screenshot's original filename (e.g. "03_statistics.png"). Pass it so that, if this render is saved as a project, the user's own screenshots folder re-loads exactly this file by name. Optional if the ref already carries a name (from request_screenshot_upload({ names })); omit entirely and the record falls back to a positional name (screen-N.png).

  4path

  A local filesystem path to a PNG, read straight off disk — ONLY available over the local stdio server (npx shotops-mcp); the hosted server rejects this entry shape.

  • pathstringrequiredat least 1 character

  • namestringoptionalat most 200 characters

    The screenshot's original filename (e.g. "03_statistics.png"). Pass it so that, if this render is saved as a project, the user's own screenshots folder re-loads exactly this file by name. Optional if the ref already carries a name (from request_screenshot_upload({ names })); omit entirely and the record falls back to a positional name (screen-N.png).

  5locales

  Per-locale variants of ONE screenshot: { "locales": { "en-US": <entry>, "de-DE": <entry> } } (each variant is an inline base64 / ref / url / path entry). render_strip picks the top-level locale's variant; emit_bundle with locales renders/packages every listed locale. A locale with no variant of its own falls back to the en-US variant (else the first declared), so you can localize only some screenshots.

  • localesobjectrequired

Result

• okbooleanrequired

• countnumberoptional

• panelPresetIdstringoptional

• panelWidthnumberoptional

• panelHeightnumberoptional

• renderMsnumberoptional

• outputstringoptional

  one ofinlineurls

• localestringoptional

• nextStepobjectoptional

  • actionstringrequiredalways "offer_save_project"

    An offer to put to the user. Never a command, and never consent already given.

  • toolstringrequiredalways "save_project"

    The door that would persist this work, if they ask for it.

  • projectCreatedbooleanrequiredalways false

    No project was created or updated by this call — the same fact as contract.effects.projectMutation.

  • consentstringrequiredalways "required"

    Saving needs the user’s own preserve/reuse/keep-editing intent. A client that cannot ask returns this offer unresolved rather than saving.

  • reasonstringrequired

• creditsobjectoptional

  Credits this call spent from the account wallet, the balance left afterwards, and when that wallet is next topped up (ISO 8601; absent when no further refill is scheduled). Renders cost per panel; reads, saves, uploads and deletes are free, as is bundling panels that were already rendered.

  • debitednumberrequired

  • remainingnumberrequired

  • refillAtstringoptional

• notestringoptional

  Free-text advisories about THIS call, joined into one string. Written when the server did something you did not literally ask for or could not have known: a look/version fallback, an output-mode downgrade, a device this server cannot render, a style.shotLook a look overrode, or placement set by hand where a style.layout template would have produced the same composition. Never an error — the call succeeded. Read it, and act on it next call.

• layoutobjectoptional

  What is wrong with this render’s COMPOSITION, measured on the panels it just returned. ABSENT means there is nothing to report — a clean strip, or one whose captions could not be measured. Advisory: the panels are already rendered and nothing here changed a pixel.

  • findingsarrayrequired

    each item

    object

    • kindstringrequired

      What overlaps what. Captions must never overlap each other or a device; devices MAY overlap, and are only reported here when the pair does NOT read as composed (no real difference in scale, camera angle or roll).

      one ofcaption-captioncaption-devicedevice-device

    • framesarrayrequired

      0-based indexes into the returned panels. For a caption finding the FIRST entry is the frame whose caption is the one to change; a second appears only when the other party sits in a different frame.

      each item

      number

    • depthPctnumberrequired

      How deep the overlap runs, in whole percent of panel height — or, for device-device, the percentage of the smaller device the other one covers.

    • anchoredbooleanrequired

      true ⟹ a caption was placed by hand (an explicit anchor), so nothing may rewrite it.

    • clearAtScalenumberoptional

      The verified factor that clears this frame’s auto-placed captions — 0.82 means 82% of their current size. Absent when no size above the legibility floor clears it, or when the offending caption is a hand placement.

  • correctedLookanyoptional

    The look this render used, with every caption shrunk to the largest size verified to clear the overlap. Pass it back as look to re-render. Absent when no repair is deterministic — a device-device overlap is a taste call (give the pair a real difference in scale, angle or roll) and a hand-anchored caption is a human placement. note says which.

• contractobjectoptional

  The versioned ShotOps result contract (#662): what ran, where, what it changed, what it cost, what it produced and — on a refusal — a typed failure over a closed code catalog. Structured content is authoritative; the prose beside it is a rendering of this block.

  • contractVersionstringrequired

    The version of THIS envelope, REPORTED. Compare it against the version you were written for. There is no version negotiation: no tool accepts a requested version, so this is never a refusal — it moves only when a field changes meaning, and additive fields never move it.

  • statusstringrequired

    one ofsucceededpartialfailedrefusedacceptedqueuedrunningcancel_requestedcancelled

  • terminalbooleanrequired

    false ⟹ this operation is still running and will be reported again (#666).

  • operationobjectrequired

    • idstringrequired

      Identity for THIS call, unique per invocation. Quote it in a bug report.

    • toolstringrequired

      The registered tool name that produced this result.

    • kindstringrequired

      one ofrenderbundlereadmutateuploaddeletestatus

    • durableobjectoptional

      #666 domain handle for addressable long-running work. Absent from synchronous calls.

      • operationIdstringrequired

      • pollWithstringoptional

  • executionobjectrequired

    • locationstringrequired

      Where the work RAN. local is the caller’s own machine over stdio.

      one oflocalhosted

    • inputModesarrayrequired

      Every way this door accepts screenshots and assets.

      each item

      string

      one ofinline_base64stored_refremote_urllocal_pathproject_stored

    • deliveryModesarrayrequired

      Every way this door can hand a result back.

      each item

      string

      one ofinline_base64signed_urllocal_pathshare_link

  • effectsobjectrequired

    What this call DID to the world, independent of what it returned. Every flag is stated on every result, false included: an absent flag would be indistinguishable from an effect nobody thought to declare.

    • networkFetchbooleanrequired

      This call fetched bytes from a host neither ShotOps nor the caller controls.

    • uploadbooleanrequired

      Caller bytes were uploaded into ShotOps storage.

    • retainedStoragebooleanrequired

      Something survives this call in ShotOps storage.

    • projectMutationbooleanrequired

      A saved project or its look history changed.

    • publicationbooleanrequired

      Something became reachable outside the account — a share link.

    • deletionbooleanrequired

      Something was permanently removed.

  • costobjectrequired

    • unitstringrequiredalways "credit"

      Public cloud credits — the same unit every ShotOps surface quotes.

    • modelstringrequired

      How this connection pays. unmetered is local stdio, which renders on the caller’s own machine; anonymous_allowance is the unsigned hosted taste.

      one ofmeteredanonymous_allowanceunmetered

    • estimatednumberoptional

      What the call was expected to cost, before it ran.

    • reservednumberoptional

      Held against the wallet for the duration of the call (#666).

    • releasednumberoptional

      Given back — an unused reservation or a refund after a post-charge failure (#666).

    • settlednumberoptional

      Actually taken. Absent when nothing was charged.

    • balanceAfternumberoptional

      The wallet’s public cloud credit balance once this call settled.

    • refillAtstringoptional

      ISO 8601. When the wallet is next topped up; absent when none is scheduled.

  • progressobjectoptional

    Persisted monotonic durable-operation progress. Never inferred from transient render metadata. Relay panelsCompleted/panelsTotal and the estimate to the waiting user; the item counters are internal bookkeeping and do not match what they asked for.

    • completedintegerrequiredmin 0

      Internal scheduling items done — panels PLUS the bundle and result items. Do not quote this to a person.

    • totalintegerrequiredmin 0

      Internal scheduling items in total. Larger than the panel count.

    • panelsCompletedintegeroptionalmin 0

      Panels finished, in the unit the caller asked in. THIS is the number to report.

    • panelsTotalintegeroptionalmin 0

      Panels this operation will produce — the count the user asked for.

    • attemptintegerrequiredmin 0

    • heartbeatAtstring or nulloptional

    • estimatedRemainingSecondsnumberoptionalmin 0

      Rough seconds of rendering left, from this operation’s own measured pace once a panel has landed. An estimate, not a deadline — say “about”. Absent when nothing is left to render.

  • resolvedInputobjectoptional

    #661 — what the server actually resolved the request to, before any pixel was produced.

    • snapshotIdstringoptional

      psi_ + the first 32 hex of the fingerprint. Quote it in a bug report.

    • fingerprintstringoptional

      sha256 over every resolved fact. Equal fingerprints ⟹ equal production input.

    • sourcesarrayoptional

      One entry per source cell, resolved or not. slot is the cell the bytes came FROM — a shot id and coordinate on a saved project, an ordered slot label on a direct render. Never a filename, a ref or a URL. origin is absent exactly when status is not resolved: there is nothing the cell came from.

      each item

      object

      • slotstringrequired

      • statusstringrequired

        one ofresolvedmissingambiguous

      • originstringoptional

        one ofinline_base64stored_refremote_urllocal_pathproject_stored

    • defaultsAppliedarrayoptional

      What the server chose because the caller said nothing.

      each item

      string

    • overridesarrayoptional

      What the caller said that changed the outcome.

      each item

      string

  • readinessobjectoptional

    #665 — the readiness verdict and any waiver receipt.

    • statestringoptional

      blocked ⟹ nothing was delivered. ready_with_findings ⟹ delivered, and here is what to know.

      one ofreadyready_with_findingswaivedblocked

    • policyVersionstringoptional

      The readiness policy this verdict was computed under. A waiver granted under another one is rejected.

    • findingsarrayoptional

      Every finding, with code, waivable and digest. A waiver names one id AND its digest; there is no wildcard and no code-level waiver.

      each item

      object

      • idstringrequired

        rf_ + 24 hex. Quote it in a waiver.

      • severitystringrequired

        one ofinfowarnblock

      • messagestringrequired

      • targetobjectrequired

        The exact shot, panel, locale, output or frames this finding is about.

        • shotIdstringoptional

        • panelIndexnumberoptional

        • localestringoptional

        • outputstringoptional

        • captionLayernumberoptional

        • framesarrayoptional

          each item

          number

      • evidenceobjectrequired

        Bounded redacted facts used to derive the finding and its digest.

    • waiversarrayoptional

      The waivers this call ACCEPTED. Pass these objects back verbatim to reuse them; a rebuilt one is rejected.

      each item

      object

      • findingIdstringrequired

      • findingDigeststringrequired

      • policyVersionstringrequired

      • waivedBystringrequired

      • waivedAtstringrequired

      • codestringrequired

        one ofsource_identity_ambiguousoutput_unsupportedoutput_omittedlook_exact_unavailableno_panelspanel_invalid_pngpanel_dimensions_invalidrenderer_failedinput_changed_during_runpanel_source_emptylocale_source_fallbackdevice_source_fallbackcaption_inheritedcaption_locale_fallbacklook_source_fallbackcaption_device_collisioncaption_caption_collisiondevice_device_collisioncaption_legibility_unresolvedscope_filteredlocale_not_live_on_applelook_hold_inactivecaption_text_empty

      • reasonstringoptional

  • artifactsarrayoptional

    each item

    object

    • idstringrequired

      The opaque asset id from the custody registry (#663) — or, for kind: "share", the link’s own token. Never a storage path, and never a signed URL.

    • kindstringrequired

      one ofpanelbundlescreenshotshareproject

    • deliveryobjectrequired

      • modestringrequired

        one ofinline_base64signed_urllocal_pathshare_link

      • urlstringoptional

        THE ONE FIELD a signed URL may appear in. Nothing else in this envelope carries one.

      • expiresAtstringoptional

        ISO 8601, when the grant above stops working.

    • bytesnumberoptional

    • retainedUntilstringoptional

      ISO 8601, when ShotOps stops keeping the artifact itself.

  • failureobjectoptional

    Present exactly when status is failed or refused.

    • codestringrequired

      The closed failure code. Branch on this, never on the sentence.

      one ofinvalid_inputunsupported_inputproject_not_foundproject_ambiguousno_projectsversion_not_foundresolution_incompletereadiness_requiredreadiness_unmetasset_not_foundasset_in_useauthentication_requiredplan_requiredtrial_choice_requiredquota_exhaustedanonymous_limit_reachedcapability_deniedbilling_unavailablerender_failedstorage_failedpersistence_failedupstream_unavailablepayload_too_largerate_limitedoperation_not_foundidempotency_conflictoperation_unavailableoperation_not_readycontract_version_unsupportedinternal_error

    • phasestringrequired

      How far the call got. input and authorization guarantee nothing was rendered, stored, written or charged.

      one ofinputauthorizationresolutionreservationexecutiondeliverypersistence

    • retryablebooleanrequired

      true ⟹ the identical call may succeed later with nothing changed.

    • nextActionstringrequired

      The one move that resolves this, machine-readable.

      one ofnonefix_inputchoose_projectupload_assetsreduce_scopesign_inchoose_planupgrade_planretrywait_and_retrypoll_operationupgrade_clientcontact_support

    • detailsobjectoptional

      Bounded, redacted, code-specific facts (the offending field name, the candidate project ids, the required plan). Never a credential, a signed URL or screenshot bytes.

• panelsarrayoptional

  each item

  one of 3 shapes

  1string

  2ref

  • refstringrequired

  • urlstringrequiredformat uri

  3position

  • positionintegerrequiredmin 1

  • contentIndexintegerrequiredmin 1

  • mimeTypestringrequiredalways "image/png"

  • deliverystringrequired

    one ofimageresource_link

  • refstringoptional

• operationIdstringoptional

• statusstringoptional

  one ofacceptedqueuedrunningcancel_requestedsucceededfailedcancelled

• progressobjectoptional

  • completednumberrequired

  • totalnumberrequired

  • panelsCompletednumberoptional

    Panels finished — the number to report to the user.

  • panelsTotalnumberoptional

    Panels this operation will produce.

  • attemptnumberrequired

  • heartbeatAtstring or nulloptional

  • estimatedRemainingSecondsnumberoptional

    About how many seconds of rendering are left. An estimate — say “about”.

• failureanyoptional

Example

That request maps to this call:

{
  "name": "render_strip",
  "arguments": {
    "screenshots": [
      {
        "ref": "uploads/you/tidebook/01-today.png"
      },
      {
        "ref": "uploads/you/tidebook/02-forecast.png"
      }
    ],
    "style": {
      "layout": "standard",
      "captions": [
        {
          "text": "Know the tide before you go"
        },
        {
          "text": "Seven days of swell"
        }
      ]
    },
    "preview": true
  }
}

One base64 PNG per panel, the panel size it rendered at, and — when the composition needs attention — a layout block naming every caption sitting on a device and, where the repair is deterministic, a corrected look you can pass straight back.

Access and cost

• Preview renders are open to everyone, including a hosted caller with no account.
• A full-resolution render is production output: it needs an active Pro trial or Pro, and the server decides that before any pixel is rendered or any cloud credit is spent.
• On the hosted server a preview panel costs 1 cloud credit and a full-resolution panel 4. On the local stdio server rendering is free and spends nothing.
• Without an account the hosted server allows 3 preview attempts per network per 30 days, up to 5 panels each.

When it refuses

The reply says production output is not available.

That is an entitlement answer, not a render failure — nothing was rendered and nothing was charged. Call account_status, do the step it names, then retry. Previews keep working.

A full-resolution screenshot is rejected as too large.

Inline base64 is capped for small payloads. Import the file first (import_screenshot for a URL or a ChatGPT attachment, request_screenshot_upload for a file on the user’s disk) and pass the returned ref instead.

The result carries a layout block full of findings.

The composition measured badly — captions are landing on devices. Pass layout.correctedLook back as look and re-render, or pick a different layout template from the longest headline in the set.

A path entry is refused.

Reading a file off disk only works on the local stdio server. On hosted, use a URL or a signed upload.

Where this fits

• The whole path from screenshots to a bundle
• Rendering one locale at a time

What the agent is told

The title and description the server publishes on tools/list — this is the copy a model chooses between, reproduced verbatim.