save_look

What it does

• Writes
• Account required

Make a design reusable. Once the user is happy with how a strip looks, this stores the styling on a project as a new version — so their next render, here or in the web app, starts from what they approved instead of a default. Styling only: caption words are never stored, so pass those per render.

You can ask: “Save the Look I just approved as a new project version.”

Input

• projectstringoptionalat least 1 character

  Project id or exact name. Omit for the most recently edited project.

• lookobjectrequired

  The look to save, styling only. Fields: describe_look.

• sourceNamestringoptionalat most 120 characters

  Where this styling came from.

What the server actually accepts

The published schema above deliberately accepts a wider shape for look, sourceName, 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.

• lookobjectrequired

  The look JSON to save (styling only — the shape read_look returns / describe_look documents). Caption text is NOT part of a look; pass it per render instead.

  • 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 = 1320×2868. 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.

      • deviceSizestring 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 blue. These are finish SLOTS — each device binds its own real finish. On iPhone: blue = Deep Blue, silver = Silver, orange = Cosmic Orange, ice = Glacier, red = Burgundy, black = Black. A slot a device does not bind falls back to its first finish — "green" is Pixel-only (Jade).

        one oforangeblueicesilverredblackgreencustom

      • 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).

      • deviceFramebooleanoptional

        Render the 3D device frame around the screen. Default true. Set false for a flat rounded screenshot card with no device chrome — screenCornerRadius then sets its corner rounding, and roll still rotates the flat card exactly as it tilts a framed device.

      • screenCornerRadiusstring or numberoptional

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

• sourceNamestringoptionalat most 120 characters

  Where this styling came from (shown in the studio UI).

Result

• okbooleanrequired

• projectobjectoptional

  • idstringrequired

  • namestringrequired

• versionnumberoptional

• notestringoptional

  Advisories: fallbacks, clamps, downgrades. Never an error.

• messagestringoptional

Example

That request maps to this call:

{
  "name": "save_look",
  "arguments": {
    "project": "Tidebook 2.4 launch",
    "look": {
      "bgMode": "gradient",
      "gradientStops": [
        {
          "color": "#0d2b3d",
          "at": 0
        },
        {
          "color": "#6aa9c9",
          "at": 1
        }
      ]
    }
  }
}

The version number it was saved as. Earlier versions stay readable through read_look.

Access and cost

• Needs an account. Not available to an anonymous hosted caller.
• Free. Saving a look spends no cloud credits and renders nothing.

When it refuses

A field is rejected as out of range.

The reply names the field, its range and the fix in prose. This is the one door where an out-of-range pose would get persisted, which is why it is checked here rather than at render time.

Where this fits

• Saving and reading look versions

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.