niche_render_image_card

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "Session UUID that's reached cp3_awaiting_review or complete."
    },
    "scope": {
      "type": "string",
      "enum": [
        "full",
        "recomposite",
        "restore",
        "reframe"
      ],
      "description": "'full' (default): render a new visual (background required). 'recomposite': free text edit on the existing image, with new headline/subhead/color/size composited over the retained background, pixels otherwise identical, synchronous, 0 credits. Use this for wording iteration; it avoids paying a re-render to change words. 'restore': bring back the prior image from history, free. 'reframe': free per-platform aspect variant that re-composites an existing card's retained background at the `cell`'s canvas size (x 16:9, instagram 4:5, linkedin 1.91:1), same text and grounding, synchronous, 0 credits. Requires `cell` (the target aspect)."
    },
    "background": {
      "type": "string",
      "enum": [
        "photo",
        "brand_color",
        "design",
        "svg"
      ],
      "description": "Required for scope='full' (ignored otherwise): what's behind the text. 'photo' = a generated AI/photographic image (the actual picture; ~30 credits, ~30-90s, async). 'design' = a generated editorial design graphic that draws the argument (concept diagram / stat / pull-quote / comparison / method / abstract), on-brand and legible, no photo, no clichés, ~30 credits, async. 'brand_color' = a free, instant flat brand card (no generation). 'svg' = a free, instant card you author exactly as SVG markup (pass `svg`), rasterized at the cell's size; best for data, labels, and charts, and the only visual that works from a network-locked sandbox. No default: choose deliberately."
    },
    "svg": {
      "type": "string",
      "description": "Required when background='svg': the card's SVG markup as a string (<svg ...>...</svg>). You author the exact layout; the server rasterizes it to the cell's pixel dimensions. Use brand colors and fonts from niche_whoami to stay on-brand. Bundled fonts (set font-family to any by name; an unknown family or the generics 'sans-serif'/'serif'/'monospace' fall back to a real font so text always draws): sans (Inter, Geist, Open Sans, Montserrat, Lato, Poppins, DejaVu Sans), serif (DejaVu Serif, Lora, Playfair Display), mono (DejaVu Sans Mono, JetBrains Mono). Allowed: static shapes, paths, text, gradients, internal (#id) and inline data: references. Rejected with a named error: scripts, event handlers, foreignObject, external/file references, and DOCTYPE/ENTITY declarations. Max 512KB."
    },
    "design_concept": {
      "type": "string",
      "description": "Optional, background='design' only: free-text art direction for the design graphic, the layout/shape and concept (e.g. 'a 2-column comparison', 'an abstract composition, no literal imagery', 'a concept diagram of intended vs actual'). Omit to let the designer pick the shape that best carries the argument."
    },
    "design_color": {
      "type": "string",
      "description": "Optional, background='design': color control for the design card. Free text. Sets the card BACKGROUND when the phrase names a background or the card overall ('cream background', 'navy', 'on a green card'), or the ACCENT when it names one ('blue accent', '#0a3d62'); the rest stays on the brand's palette (or the default style when the brand has no kit). Omit to use the brand's palette."
    },
    "subhead": {
      "type": "string",
      "description": "The smaller line under the header. On scope='full' it sets the subhead in the single render; on scope='recomposite' it edits it for no charge. Omit to keep the current one; pass '' to clear it."
    },
    "text_color": {
      "type": "string",
      "description": "Text color as a name ('blue') or hex ('#ec4899'). Applies on scope='full' (set the color in the render) and scope='recomposite' (re-color for no charge). On background='brand_color' it colors the card text; omit to auto-pick a legible color from the background."
    },
    "background_color": {
      "type": "string",
      "description": "The background colour of a SOLID brand card (background='brand_color') as a name ('cream'/'navy'), a hex, or a brand keyword ('primary'/'accent'/'secondary'). Applies on a full brand_color render AND on scope='recomposite' (free, persists, so the colour does not snap back to the brand default on a later edit). (A generated-photo card recolours its text, not its photo background.)"
    },
    "font_size": {
      "type": "string",
      "description": "Headline size. A relative word ('bigger'/'smaller'/'reset') steps from the current size and compounds; an absolute value (a number like 80, '80px', or '120%') sets it directly. Applies on scope='full' and scope='recomposite'. The response's font_changed/font_at_limit report whether it actually moved."
    },
    "text_position": {
      "type": "string",
      "description": "Where the overlay sits: 'top', 'center', or 'bottom'. On scope='full' it places the text in the render; on scope='recomposite' it moves the text on the existing image for no charge. Omit to keep the position the card was rendered at."
    },
    "needs_legible_text": {
      "type": "boolean",
      "description": "scope='full', background='photo' only. Set true when in-image text is genuinely the subject of the scene, which routes the render to a text-capable image generator. Defaults false (an atmospheric, text-free background, the usual choice)."
    },
    "headline": {
      "type": "string",
      "description": "The bold header words; works for both backgrounds. Defaults to the post's `card_headline` (the short, sized-for-the-box line). Pass this to force exact text, e.g. a brand name leading it ('Acme drew a line'). It auto-fits the box and is never truncated."
    },
    "art_direction": {
      "type": "string",
      "description": "Optional free-text direction for a generated photo background (applies only when background='photo'). State the visual concept and any negatives, such as subjects or styles to avoid. Without it the background is generated from the story alone and tends toward category clichés (e.g. a robot for 'AI'); use this to steer toward a specific concept or an abstract, non-literal composition. The no-in-image-text rule still applies."
    },
    "cell": {
      "type": "string",
      "description": "Optional. Render at the canvas size for this cell:\n  • linkedin:image_post: 1200×627 (1.91:1 landscape)\n  • x:image_post: 1200×675 (16:9 landscape)\n  • instagram:image_post: 1080×1350 (4:5 portrait)\n  • linkedin:carousel / instagram:carousel: 1080×1080 (cover slide)\nWhen omitted: 1080×1080 universal-square asset stored under platform='image_card' (shared across all image cells)."
    },
    "estimate_only": {
      "type": "boolean",
      "description": "If true, return {credit_cost} without rendering or spending. Use to learn the cost before committing.",
      "default": false
    }
  },
  "required": [
    "session_id"
  ]
}