Render an image card
niche_render_image_cardRender a visual onto a post at CP3, or edit an existing image.
scope: 'full' (default) renders a new visual and requires background. 'recomposite' re-composites new text, color, or size over the retained background at no charge. 'restore' reverts to the prior image from history, at no charge. 'reframe' produces a per-platform aspect variant from the retained background, at no charge.
background (required for scope='full'):
• 'photo': a generated AI/photographic image with the headline composited over it. ~30 credits, ~30-90s, asynchronous: returns status='rendering_image_card'; poll niche_session_state (image_render.status: rendering, then done with static_urls on the output, or failed with credits refunded). A repeat call while a render is in flight is a no-op.
• 'design': the INFOGRAPHIC, a generated editorial graphic that DRAWS the argument (a ranked bar chart, a two-column diagram, a stat, a before/after, a pull-quote), on-brand and legible, with vetted icons. The designer art-directs the treatment from the brand PALETTE (leads light for data, dark for narrative; accent as a spice), and honors a look steer in design_concept ('brighten it up', 'a ranked bar chart', 'navy and gold'). ~30 credits, asynchronous (poll as above).
• 'brand_color': a flat brand card with the headline on the brand's solid color with logo and wordmark. No generation, no credits, synchronous.
• 'svg': you author the card exactly as SVG markup (pass svg); the server rasterizes it to the cell's dimensions. Free, instant, deterministic. The right choice for data, labels, charts, and comparisons (where generated images fail at layout), and the only visual that works from a network-locked sandbox (SVG is text). The SVG owns the whole canvas; use brand colors and fonts from niche_whoami. Static shapes, paths, and text only (no scripts, external references, or foreignObject).
headline sets the bold header (defaults to the post's card_headline; auto-fits, not truncated). Idempotent: a prior render is replaced. Errors: render_not_ready before CP3; render_not_configured when image generation is unavailable; render_card_unavailable when background='brand_color' but the piece has no card-bearing platform.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| svg | No | 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. | |
| cell | No | Optional. Render at the canvas size for this cell: • linkedin:image_post: 1200×627 (1.91:1 landscape) • x:image_post: 1200×675 (16:9 landscape) • instagram:image_post: 1080×1350 (4:5 portrait) • linkedin:carousel / instagram:carousel: 1080×1080 (cover slide) When omitted: 1080×1080 universal-square asset stored under platform='image_card' (shared across all image cells). | |
| scope | No | '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). | |
| subhead | No | 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. | |
| headline | No | 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. | |
| font_size | No | 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. | |
| background | No | 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. | |
| session_id | Yes | Session UUID that's reached cp3_awaiting_review or complete. | |
| text_color | No | 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. | |
| design_color | No | 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. | |
| art_direction | No | 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. | |
| estimate_only | No | If true, return {credit_cost} without rendering or spending. Use to learn the cost before committing. | |
| text_position | No | 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. | |
| design_concept | No | 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. | |
| background_color | No | 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.) | |
| needs_legible_text | No | 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). |