{"schemaVersion":"1.0.0","kind":"brandiseer.use-case","id":"klaviyo-email-heroes","canonicalUrl":"https://blog.brandiseer.com/use-cases/klaviyo-email-heroes","contentHash":"2012dde3510d65aa7957834d228998c3c5a542ca75311a78ae1de954b78d31fd","metadata":{"title":"Klaviyo email heroes","outcome":"An agent generates on-brand email hero, header, and promo stills with Brandiseer; a person places imageUrl in a Klaviyo template image block or the image library. Brandiseer does not push into Klaviyo and does not send campaigns.","category":"email","featured":true,"timeEstimate":"~25 to 40 min setup","methods":["MCP","REST"],"hosts":["Cursor","Cowork"],"image":"https://blog.brandiseer.com/use-case-assets/klaviyo-email-heroes/cover-klaviyo-email-heroes.png","updated":"2026-09-24"},"stack":[{"name":"Brandiseer","role":"Brand memory and on-brand stills via MCP or REST","logo":"/logo-b.png","href":"https://brandiseer.com"},{"name":"Klaviyo","role":"Template image blocks and the image library. A person places the still.","href":"https://www.klaviyo.com"},{"name":"Cursor","role":"Agent host for Brandiseer MCP or REST"},{"name":"Claude Cowork","role":"Agent host for Brandiseer MCP or REST"}],"workflow":{"audience":"- Lifecycle, CRM, and email marketers who already send in Klaviyo and need a hero, a header still, or a promo image without opening a separate design tool for every campaign or flow\n- Agencies that keep one Brandiseer Brand ID per client and one Klaviyo account per client\n- Operators who can paste an `imageUrl` into a Klaviyo image block, or upload the file into the image library and then assign it\n\n**Ideal customer profile:** a team whose campaigns and flows already live in Klaviyo, whose brand already lives in Brandiseer, and whose missing piece is a brand-safe still plus a clear handoff into an image block or the image library.","rationale":"Klaviyo is where the email is built and sent. Cursor or Cowork is the agent that turns a brief into a layout. Brandiseer stores the logo and visual identity once, then applies that memory on every still. The prompt carries subject, layout, composition, and on-image text. It does not restate colours, fonts, mood, or visual style.\n\nA Klaviyo programme drifts when every hero is a one-off export from a general image tool. Brandiseer keeps the still on the same brand as the rest of the campaign. Klaviyo still decides which template receives the file, and a person decides when that email is sent.\n\nThis is a different job from the sibling guides:\n\n- [Slack creative desk](/use-cases/slack-creative-desk) is a request-and-return desk. A person writes a brief in Slack and an agent posts a still back in the thread.\n- [Social media automation](/use-cases/social-media-automation) writes captions and schedules posts with Buffer.\n- [Always-on creative automation](/use-cases/always-on-creative-automation) is the HTTP step in Zapier, Make, or n8n.\n- [Webflow site visuals](/use-cases/webflow-site-visuals) generates site stills and hands `imageUrl` to Webflow.\n- [HubSpot campaign creatives](/use-cases/hubspot-campaign-creatives) generates campaign stills and hands `imageUrl` to HubSpot.\n- This guide generates email heroes, headers, and promo stills and hands `imageUrl` to Klaviyo. Brandiseer does not push into Klaviyo and does not send campaigns.\n\n![Example strip: email hero, promo square, section background, and footer banner](https://blog.brandiseer.com/use-case-assets/klaviyo-email-heroes/example-strip.png)","architecture":"Architecture, from email brief to a still sitting in a Klaviyo template:\n\n1. You store the brand once in Brandiseer (logo and reference visuals teach the look).\n2. The agent host (Cursor or Cowork) has Brandiseer MCP or REST, the Brand ID (`bds_c_...`), and the standing instructions in this guide.\n3. You name the slot: email hero or header, promo still, section background, or a short footer banner. The agent rewrites that brief into subject, layout, and on-image text, then sets `aspectRatio`, `resolution`, `mode`, and `useLogo` as fields.\n4. Brandiseer returns `imageUrl`. The agent reports the URL, the crop, the mode, a suggested alt text line, and a placement note (which template and which block). It does not claim the Klaviyo template changed.\n5. A person imports or uploads the file and assigns it in the template editor. They set alt text, the click link, and the display width. They leave the campaign unsent and the flow status unchanged. Optional API steps follow Klaviyo's Images API and stop at the library.\n\n![Workflow infographic: brief, Brandiseer still, imageUrl, Klaviyo library or Import Image, a person places the image](https://blog.brandiseer.com/use-case-assets/klaviyo-email-heroes/workflow-infographic.png)","prerequisites":"- Company website URL, if the brand is not in Brandiseer yet\n- Brandiseer account with at least one finished brand profile\n- API key (`bds_...`) from [Settings → API](https://brandiseer.com/settings/api) or [Developers](https://brandiseer.com/developers)\n- Brand ID (`bds_c_...`) for every brand the agent may call\n- Credits for the stills you actually generate (see the table in Limits & FAQ)\n- Cursor or Claude Cowork, with Brandiseer MCP or a way to call REST\n- A Klaviyo account you can edit\n- Access to the email template editor (a draft campaign, a flow email, or **Email Templates**) and to **Content > Images & brand > Images**\n- Optional, only for the Images API: a Klaviyo private API key with the `images:write` scope, in the agent secret store. Requests use `Authorization: Klaviyo-API-Key` plus a `revision` header, as on [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url). This key is not the Brandiseer key. Klaviyo's remote MCP is Owner, Admin, or Manager only. This guide does not require that MCP","setup":"### Stage 1: Add your brand on Brandiseer\n\n1. Go to [brandiseer.com](https://brandiseer.com). In the homepage input, enter your company website URL and click **Try My Brand**.\n2. Wait about one minute while Brandiseer analyses the site and picks a logo and visuals.\n3. Review those visuals carefully. They teach Brandiseer your look. Every later Klaviyo still is influenced by what you leave here.\n4. Remove anything off-brand (partner logos, stock, irrelevant screenshots). Add campaign creatives or product photography that match the look you want.\n5. Click **Add Brand**, sign up if prompted, then wait about 30 seconds for the brand profile to finish.\n\nAgencies repeat this once per client. Do not point two Klaviyo accounts at one Brand ID.\n\n### Stage 2: API key and Brand ID\n\n1. Open [brandiseer.com/developers](https://brandiseer.com/developers) or [Settings → API](https://brandiseer.com/settings/api).\n2. Create an API key (`bds_...`). Put it in the agent host's secret store. Do not paste it into a Klaviyo template, a campaign, Slack, or a git repo.\n3. Copy the Brand ID (`bds_c_...`).\n4. Confirm the key with `GET https://brandiseer.com/api/v1/credits` and `GET https://brandiseer.com/api/v1/brands`, header `X-API-Key`. The credits JSON includes `credits`. The brands list includes each brand `id`.\n5. Optional reachability check, no key required: `GET https://brandiseer.com/api/v1/health` returns `{ \"status\": \"ok\" }`.\n\nRead [guide/docs](https://brandiseer.com/guide/docs) and [guide/image](https://brandiseer.com/guide/image) once while you write the standing instructions. Those pages are the live contract if a field name ever moves.\n\n### Stage 3: Connect Brandiseer to the agent host\n\nUse Cursor or Cowork. One host is enough.\n\n**A. MCP**\n\n1. Add the Brandiseer MCP server at `https://brandiseer.com/api/mcp`.\n2. Authenticate with `Authorization: Bearer` and the API key, in the secret field your host provides.\n3. Confirm the tool list shows `brandiseer_list_brands`, `brandiseer_check_credits`, and `brandiseer_generate_image`. If a fourth Brandiseer tool appears, ignore it until [guide/docs](https://brandiseer.com/guide/docs) documents it.\n\n**B. REST**\n\n1. On [Developers](https://brandiseer.com/developers), open **View Docs** and use **Copy for LLM** if you want the reference inside the session.\n2. Tell the agent to prefer `POST https://brandiseer.com/api/v2/generate` or `POST https://brandiseer.com/api/v2/generate/async` with `X-API-Key`.\n3. If Design mode times out, switch that call to async and poll `GET https://brandiseer.com/api/v2/jobs/:jobId` every 3 to 5 seconds.\n\n### Stage 4: Save the standing instructions\n\n1. Paste the **System prompt** from this guide into the Cursor rule or Cowork instructions that will run email stills.\n2. Fill the defaults the prompt asks for: Brand ID, default crops per slot, resolution, mode, and whether `useLogo` is on when the brief is silent.\n3. Ask the agent to call `brandiseer_list_brands` (or `GET /api/v1/brands`) and confirm the Brand ID exists before the first paid still.\n\n### Stage 5: Smoke test a hero in an image block\n\n1. Ask for one email hero with a layout-only brief (the Spring hero in Example flows).\n2. Confirm the agent checked the brand, avoided colour and mood words, and returned `imageUrl` plus crop, mode, and a placement note.\n3. In Klaviyo, open a **draft** campaign or an unsent template. Drag an **image block** to the top of the canvas. Add the still by **Import Image** (paste `imageUrl`), by uploading the downloaded file, or by choosing it from the Image Library after you have uploaded it under **Content > Images & brand > Images**.\n4. Set alt text, a link address if the hero should be clickable, alignment, and width. Klaviyo recommends a 600px content width, full-width images about 600 to 1000px wide and under 2000px tall, and files around 1MB or smaller. The editor accepts up to 10MB. A large Brandiseer still can be inserted and then resized in the block. Klaviyo's own tip for crispness is to use a larger source and display it smaller.\n5. Use **Preview & test**. For a campaign or a list, segment, price-drop, or date-triggered flow, search a profile. For a metric-triggered flow, preview by the triggering event. Leave the campaign unsent. Do not change a flow's status.\n6. Send a second brief that only says \"make the hero premium and moody\". The agent should ask what is physically in the frame instead of generating.\n\nIf the hero must sit behind a Klaviyo text block and button, use a section background instead of baking the headline into the image. That path is in the next stage. Prefer the image block when inbox support matters: Klaviyo documents that Outlook for Windows does not support background images, and that Yahoo Mail and AOL have partial support.\n\n### Stage 6: Optional image library import (Images API)\n\nSkip this stage if people will import or upload by hand. Use it only when a private key already exists and the still must appear in the library before someone opens the template.\n\n1. Create the key with the `images:write` scope. Authentication is documented on [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url) and the [API overview](https://developers.klaviyo.com/en/reference/api-overview): header `Authorization: Klaviyo-API-Key `, header `revision` (use the default printed on the endpoint page; this guide saw `2026-07-15`), and `accept` plus `content-type` of `application/vnd.api+json`. This is not the Brandiseer key.\n2. Generate the still in Brandiseer first. Klaviyo has to be able to fetch `import_from_url`. The same page limits that import to jpeg, png, and gif, and to 5MB. If `imageUrl` is not public, the file is larger than 5MB, or Klaviyo rejects the format, stop the API call. Download the file and upload it in the template editor instead (10MB there; JPEG, PNG, GIF, and WebP that Klaviyo converts to PNG, except animated WebP).\n3. Import with the documented call: `POST https://a.klaviyo.com/api/images`. Rate limits on that page: burst `3/s`, steady `100/m`, daily `100/d`. Body:\n\n```json\n{\n \"data\": {\n \"type\": \"image\",\n \"attributes\": {\n \"import_from_url\": \"https://...\",\n \"name\": \"spring-email-hero\",\n \"hidden\": false\n }\n }\n}\n```\n\n`import_from_url` is required. `name` defaults to the filename if you omit it. If the name already exists, Klaviyo adds a suffix. Keep `hidden` false so the file shows in the asset library. A data URI is also accepted on that page. Prefer the public `imageUrl` when it meets the 5MB and format rules.\n\n4. A `201` body includes `data.id` and `data.attributes` (`name`, `image_url`, `format`, `size`, `hidden`, `updated_at`). The `links.self` value looks like `https://a.klaviyo.com/api/images/{id}/`. Confirm with `GET https://a.klaviyo.com/api/images` (the overview's list example) using the same key and `revision` header. The Klaviyo-hosted `image_url` is what you then pick in the template. It is not yet inside an image block.\n5. If you already have the file on disk and the URL import failed, the file upload is `POST https://a.klaviyo.com/api/image-upload` with `content-type: multipart/form-data`, form fields `file` (required), optional `name`, and optional `hidden`. The overview's example uses the same `Authorization` and `revision` headers. Same 5MB jpeg, png, or gif limit. A person still places the file.\n6. Open the draft template, drag an image block, and choose the image from the Image Library. Do not send the campaign in the smoke test.\n\nThe editor's automatic compression review (compare original and compressed, or an upload setting of Compare, Use originals, or Use compressed) applies when a person uploads in the product. It is not part of the API body above. GIFs are not compressed by that tool.\n\n### Stage 7: Section background, when text must sit on the image\n\nSkip this unless the brief needs Klaviyo text or buttons on top of the still. Klaviyo recommends this over a single image full of text, because recipients who block images, and people using screen readers, still get the text. Background images fail in some inboxes (see Limits & FAQ), so also set a section colour close to the image.\n\n1. Download the still. The background article does not describe an Import URL field. It says: open the section **Styles** tab, find **Background**, click **+**, then **Browse Image Library** and upload.\n2. Add a text block and, if you need one, a button, in that section. Leave those words out of the Brandiseer prompt. Tell the agent \"empty region\" instead.\n3. In **Format**, pick Original size, Fit, Fill, or Tile. **Display on** is Content or Section, which chooses whether the image stays in the content width or spans the section.\n4. Turn **Section color** on and pick a fallback colour. For a whole-template background, use the template **Styles** tab, click **+**, and choose a library image or upload. Set a template background colour as well. Full steps: [background images](https://help.klaviyo.com/hc/en-us/articles/115005255968).\n5. Preview. Do not send.","promptingRules":"When the agent builds `prompt`:\n\n- Keep subject, layout, composition, and on-image text (what the words say and where they sit).\n- Never send brand colours, fonts, mood, or visual style. Brand memory already applies those. Style words fight the brand and produce off-brand stills.\n- Put crop in `aspectRatio`, quality in `mode`, pixel size in `resolution`, and logo on/off in `useLogo`. Those are body fields, not prompt prose.\n- Map the Klaviyo slot to a documented ratio. Email hero, header, and section background: `16:9`. Promo square: `1:1`. A card-like block in the email: `4:3`. A short footer banner: `16:9`, then the person sets a shorter display height or crops a rectangle in the image block. Brandiseer does not offer a 600px-wide email ratio. Portrait `9:16` is a poor default inside a 600px column. Use it only when the brief explicitly asks for a tall still.\n- Prefer `design` for finished email stills. `fast` is the API default if you omit `mode`, and it is the right fallback if a design job fails once.\n- Prefer `1K` or `2K`. Klaviyo asks for files around 1MB, allows 10MB in the editor, and allows 5MB on the Images API. `4K` is optional and easier to reject. PNG is the better editor choice when the still contains text. Klaviyo says PNG displays best across devices for images that contain text.\n- Set `useLogo` true only when the brief asked for a logo (or your default says so). Headlines that a Klaviyo text block will render should stay off the image. Say \"empty region\" for that area instead of describing a font.\n- Full rules: [Prompt compatibility](https://brandiseer.com/guide/image).","systemPrompts":"Paste this into Cursor or Cowork as the standing instructions for Klaviyo email stills. Replace the placeholders before the first generate.\n\n```text\nYou generate on-brand email heroes, headers, and promo stills for Klaviyo.\nBrandiseer returns an image URL. You do not push pixels into Klaviyo, and\nyou do not send a campaign or change a flow.\n\nBrandiseer:\n- MCP: https://brandiseer.com/api/mcp with Authorization: Bearer.\n Tools you may call: brandiseer_list_brands, brandiseer_check_credits,\n brandiseer_generate_image. Do not invent tool names.\n- REST: X-API-Key: bds_... (secret store only).\n Prefer POST https://brandiseer.com/api/v2/generate\n or POST https://brandiseer.com/api/v2/generate/async\n then poll GET https://brandiseer.com/api/v2/jobs/:jobId every 3 to 5 seconds\n until data.status is done or failed, or about 10 minutes have passed.\n- Live contract: https://brandiseer.com/guide/docs and\n https://brandiseer.com/guide/image\n\nDefaults for this account (fill in once):\n- Brand ID: bds_c_...\n- Email hero, header, and section background aspectRatio: 16:9\n- Promo square aspectRatio: 1:1\n- mode: design\n- resolution: 2K (use 1K if a 5MB Klaviyo API import is in play)\n- useLogo when the brief is silent: false\n- Multi-brand map, if any: brand name to bds_c_...\n\nOn every request:\n1. Resolve brandId from the brief or the default. If more than one brand\n exists and the brief does not name one, ask. Never fall through to\n another client's Brand ID.\n2. Check credits before a batch (brandiseer_check_credits or\n GET https://brandiseer.com/api/v1/credits). A single still can proceed\n if the last known balance covers the mode and resolution in the table\n you were given. On 402, stop.\n3. Rewrite the brief into subject, layout, composition, and on-image text.\n Strip colours, fonts, mood, and visual style. If stripping leaves no\n physical subject, ask what is in the frame. Do not generate.\n4. Choose aspectRatio from the slot. Put resolution, mode, and useLogo in\n API fields, not in the prompt. Do not invent a 600px email ratio.\n5. Generate one still. Return imageUrl, aspectRatio, mode, resolution,\n useLogo, a one-line alt text suggestion, and a placement note:\n image block (hero, header, promo, or footer) or section background.\n6. Do not tell the user the Klaviyo template changed unless they confirm\n they placed the file. Do not send, schedule, or publish.\n\nKlaviyo, only when the human already supplied a private key and asked\nto import the file into the image library:\n- Authorization: Klaviyo-API-Key, the private key. Never the Brandiseer key.\n- revision header: copy it from\n https://developers.klaviyo.com/en/reference/upload_image_from_url\n- POST https://a.klaviyo.com/api/images\n content-type application/vnd.api+json\n data.type = image\n data.attributes.import_from_url = the Brandiseer imageUrl\n data.attributes.hidden = false\n- jpeg, png, or gif, maximum 5MB, scope images:write.\n If the file is larger or the format is rejected, tell the human to\n upload it in the template editor. Do not invent a workaround URL.\n- A 201 means the library has the image. It does not mean an image\n block was filled. A person still places it.\n- File upload, only if they already have the bytes:\n POST https://a.klaviyo.com/api/image-upload as multipart form file.\n Same size and format limits. Read the Upload Image From File page.\n- Do not call campaign send, template update, or flow update tools.\n\nOut of scope:\n- Slack replies, Buffer scheduling, and Zapier, Make, or n8n scenarios.\n- Webflow site placement and HubSpot files, pages, or ads.\n- Legal approval of claims, prices, or offers printed on the image.\n- GET https://brandiseer.com/api/v1/usage (browser session only).\n```\n\n### Prompt rewriter\n\nUse this when a brief arrives as messy notes. It does not call Brandiseer. It only cleans text before you put it in `prompt`. The word list is a starting filter, not an official dictionary. If a phrase still describes colour, type, mood, or look, delete it by hand.\n\n```javascript\n// Local rewriter for a Cursor or Cowork helper script.\n// Keeps subject, layout, composition, and on-image text.\n// Strips colour, type, mood, and visual-style language.\n\nconst STYLE_WORDS =\n /\\b(colou?rs?|palette|hex|fonts?|typefaces?|typography|serif|sans-serif|moods?|vibes?|aesthetics?|minimalist|luxury|playful|cinematic|pastel|neon|gradients?|moody|elegant|premium|on-brand)\\b/gi;\n\nconst SLOT_TO_RATIO = {\n hero: \"16:9\",\n header: \"16:9\",\n banner: \"16:9\",\n footer: \"16:9\",\n section: \"16:9\",\n background: \"16:9\",\n \"16:9\": \"16:9\",\n promo: \"1:1\",\n square: \"1:1\",\n \"1:1\": \"1:1\",\n card: \"4:3\",\n \"4:3\": \"4:3\",\n portrait: \"9:16\",\n \"9:16\": \"9:16\",\n};\n\nfunction rewriteBrandiseerPrompt(input) {\n const headline = String(input.headline || \"\").trim();\n const subject = String(input.subject || input.brief || \"\").trim();\n const slotKey = String(input.slot || input.crop || \"\").trim().toLowerCase();\n const aspectRatio = SLOT_TO_RATIO[slotKey] || \"\";\n\n let prompt = [subject, headline ? `On-image text: \"${headline}\".` : \"\"]\n .filter(Boolean)\n .join(\" \");\n\n prompt = prompt\n .replace(/#[0-9a-f]{3,8}\\b/gi, \" \")\n .replace(STYLE_WORDS, \" \")\n .replace(/\\s+/g, \" \")\n .trim();\n\n return {\n prompt,\n aspectRatio,\n needsSubject: prompt.length < 12 || !aspectRatio,\n };\n}\n```\n\nIf `needsSubject` is true, ask the human for a subject and a slot. Do not POST.","addOns":"Add these after the hero smoke test passes. They do not change Brandiseer's image contract, and they do not give Brandiseer a send button.\n\n### Approval before send\n\nAfter `imageUrl` is in the image block or on the section, a named reviewer uses **Preview & test**. Only then may someone schedule or send, in Klaviyo, as a separate step. Until that happens, leave the campaign as a draft and leave flow emails unreleased. Brandiseer does not approve legal claims, prices, or offers.\n\n### One brand per Klaviyo account\n\nKeep a table: Klaviyo account name, private-key secret name (only if you use stage 6), and `bds_c_...`. Require an account name on every brief when more than one account exists. If the name misses, stop and list the accounts you configured. Confirm Brand IDs with `GET /api/v1/brands`. Never fall through to another client's Brand ID or another account's key.\n\n### Credit soft-limit\n\nWhen `credits` is under a threshold you choose (for example 40), switch new email stills to `mode: fast` and `resolution: 1K`, or skip them. Fast at 1K costs 4 credits. An explicit \"run anyway\" from the human can override the skip. The threshold is yours, not a Brandiseer default.\n\n### Placement log\n\nKeep a short note next to the work: campaign or flow name, template, slot, `brandId`, `mode`, `aspectRatio`, `resolution`, `imageUrl`, and whether it was imported into an image block or uploaded for a section background. Brandiseer does not write this log. Klaviyo does not send it back to Brandiseer.\n\n### Reuse the block\n\nWhen the hero image block looks right, a person can save that block or section with the star icon in the template editor. Klaviyo calls this universal content. Later templates can insert it from the Universal tab. Edits can be applied to every copy. That save is a Klaviyo editor action. Brandiseer does not sync it. See the universal content section of the [template editor guide](https://help.klaviyo.com/hc/en-us/articles/4407911841435).\n\n### Dynamic image (not the default still)\n\nA Brandiseer `imageUrl` is one still for this send. Klaviyo's Dynamic Image option is a different feature: a personalisation tag from profile or event data, pasted into **Select image > Dynamic Image**. Use it only when that variable already exists. The help article shows filters such as `{{ event.image_url|missing_product_image }}` and a `default` filter with your own backup URL. Read [How to insert a dynamic image](https://help.klaviyo.com/hc/en-us/articles/4408810769307) before you paste a tag. This guide does not write profile properties and does not invent event paths.\n\n### Handoff to the sibling guides\n\n- Stills requested in Slack, returned in a thread: [Slack creative desk](/use-cases/slack-creative-desk).\n- Captions and a Buffer schedule: [Social media automation](/use-cases/social-media-automation).\n- A Zapier, Make, or n8n trigger that should deliver `imageUrl` on a schedule: [Always-on creative automation](/use-cases/always-on-creative-automation).\n- A homepage hero that lives in Webflow: [Webflow site visuals](/use-cases/webflow-site-visuals).\n- An email header, landing page, or ad that lives in HubSpot: [HubSpot campaign creatives](/use-cases/hubspot-campaign-creatives).\n\nDo not embed Buffer, a Slack desk, an always-on scenario, Webflow, or HubSpot inside this Klaviyo guide.\n\n### Optional motion (not the email MVP)\n\nMost inboxes strip embedded video. Klaviyo's video block does not play inside the email. You paste a YouTube, Vimeo, TikTok, or other hosted video URL, and a click opens a new tab. YouTube can supply a thumbnail. Other hosts need a thumbnail you upload. That thumbnail can be a Brandiseer still. The video URL is yours.\n\nBrandiseer video is a separate contract. Generate the still first, then send its public `imageUrl` to `POST https://brandiseer.com/api/v2.1/video/generate`. Poll `GET https://brandiseer.com/api/v2.1/video/jobs/:jobId`. Video jobs use `status` `completed` and a `videoUrl`, which is different from image jobs (`done` and `imageUrl`). Read [guide/video](https://brandiseer.com/guide/video) for tier, duration, and resolution before you enable this. Video credits are per second and are not the still table below. A video failure does not undo the still. Leave this off unless the brief explicitly asks to animate, and still do not send the campaign from this guide.","limitsAndFaq":"### Does Brandiseer update Klaviyo templates or send campaigns?\n\nNo. Brandiseer returns `imageUrl`. A person imports that URL into an image block, uploads the file, or picks it from the image library, then sets alt text and width. A library import through the Images API only stores the file. It does not assign a block. Sending and flow changes stay in Klaviyo, after a person reviews the draft.\n\n### Is there a Brandiseer app inside Klaviyo?\n\nNo. There is no Brandiseer block in the template editor in this guide. Do not look for a native \"send to Klaviyo\" button on the Brandiseer side.\n\n### What if Klaviyo rejects the image?\n\nThe template editor supports JPEG, PNG, and GIF, and can convert a non-animated WebP to PNG. Editor uploads are capped at 10MB. Klaviyo recommends about 1MB or smaller, 72dpi, full-width images about 600 to 1000px wide and under 2000px tall, because large files load slowly. The Images API import and file upload are stricter: jpeg, png, or gif, maximum 5MB. If the API returns an error, or the file is over 5MB, download the still and upload it in the editor. Crop inside the image block if you need a circle, square, or custom rectangle. Klaviyo keeps the full image, so the crop can be changed later.\n\n### Which Klaviyo calls are in this guide?\n\nOnly calls confirmed on Klaviyo's public docs, and only at the level those pages describe:\n\n- Human placement: image block sources (Image Library, Upload Image, Import Image, Dynamic Image) on the [template editor](https://help.klaviyo.com/hc/en-us/articles/4407911841435) guide, file types and the 10MB cap on [email images](https://help.klaviyo.com/hc/en-us/articles/115005253688), library path **Content > Images & brand > Images** on that same article, and section or template backgrounds on [background images](https://help.klaviyo.com/hc/en-us/articles/115005255968).\n- Optional library import: `POST https://a.klaviyo.com/api/images` on [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url), scope `images:write`, `revision` header, 5MB, jpeg/png/gif.\n- Optional file upload: `POST https://a.klaviyo.com/api/image-upload` on [Upload Image From File](https://developers.klaviyo.com/en/reference/upload_image_from_file) and the [Images API overview](https://developers.klaviyo.com/en/reference/images_api_overview).\n- Optional read-back: `GET https://a.klaviyo.com/api/images`, and the `self` link the create response returns.\n\nThis guide does not document a \"set the hero block\" endpoint. It does not call campaign send.\n\n### Can I use Klaviyo's own MCP?\n\nKlaviyo documents a remote MCP server at `https://mcp.klaviyo.com/mcp` for Owner, Admin, or Manager roles. See [Klaviyo MCP server](https://developers.klaviyo.com/en/docs/klaviyo_mcp_server). This guide does not connect it and does not depend on it. That page lists many tools, including `upload_image_from_url` (remote) and `upload_image_from_file` (not marked available on the remote server), plus template writers and `send_campaign`. Do not use those send or template tools for this workflow. If `upload_image_from_url` is actually exposed in your client, it is still only a library import. A person places the image block. Do not assume a tool fills a hero.\n\n### Where do the keys live?\n\nThe Brandiseer key (`bds_...`) and any Klaviyo private key live in the agent host's secret store. Never in a template, a campaign preview, a Slack message, a prompt you commit, or a workflow export in git. Rotate either key if it leaks. Poll a Brandiseer job with the same Brandiseer key that submitted it. Call Klaviyo with the Klaviyo key.\n\n### What do stills cost?\n\nCredits per still. Failures refund. Async submits deduct immediately and refund if the job fails.\n\n| Mode | 1K | 2K | 4K |\n| --- | --- | --- | --- |\n| Fast | 4 | 6 | 8 |\n| Design | 5 | 6 | 8 |\n| Pro | 6 | 8 | 10 |\n\n`402` means not enough credits. Pricing context: [brandiseer.com/pricing](https://brandiseer.com/pricing).\n\nKlaviyo's URL and file upload endpoints add their own cap: 100 uploads a day on the pages fetched for this guide, plus burst `3/s` and steady `100/m`. Hand uploads in the editor are not that API counter. If you are importing a large batch through the API, stay under the daily cap or switch the rest to the editor.\n\n### Why is the still off-brand?\n\nAlmost always because the prompt contained colours, fonts, mood, or visual style. Strip them and generate again. See [guide/image](https://brandiseer.com/guide/image).\n\n### Why does the crop look wrong in the email?\n\nBrandiseer aspect ratios are `1:1`, `16:9`, `9:16`, and `4:3`. Klaviyo emails are usually about 600px wide. Generate the hero at `16:9`, import it, then set the image block width and, if needed, crop a rectangle in the editor. Do not ask Brandiseer for a custom pixel size inside the prompt.\n\n### Why did the background disappear in Outlook?\n\nKlaviyo documents that Outlook for Windows does not support background images, and that Yahoo Mail and AOL have partial support. The section or template background colour shows instead. Put the offer in a text block, or place the still in an image block when that inbox matters.\n\n### How long can I poll?\n\nAbout 10 minutes, then the Brandiseer job expires. Poll every 3 to 5 seconds. Stop on `done` or `failed` as well. Do not start a second job for the same slot while the first is still open, or you will pay twice.\n\n### Which generate URL should new email work use?\n\n`POST /api/v2/generate` when the agent host waits long enough. `POST /api/v2/generate/async` when it does not. Legacy `POST /api/v1/generate` remains for older callers and only supports Fast and Pro via `proMode` boolean.\n\n### Does the agent approve claims on the image?\n\nNo. If the still has a price, a discount, or a legal line, a person reads it before send. Brandiseer does not review the claim.\n\n### Does deleting the library file remove it from the email?\n\nKlaviyo's image article says deleting an image from **Content > Images & brand > Images** does not remove it from templates that already use it. Do not treat a library delete as an unsend.","demo":"**Motion brief only. This is not an embed, and there is no walkthrough URL yet.**\n\n**Working title:** Klaviyo email heroes\n**Length:** 45 to 75 seconds\n\n**Story beats:**\n\n1. A person asks Cursor or Cowork for an email hero with a layout-only brief\n2. The agent calls Brandiseer (MCP or REST v2) and shows an on-brand still\n3. `imageUrl` is imported into a Klaviyo image block on a draft template\n4. Optional cut: the same file is uploaded as a section background, with a text block and button on top, still unsent\n5. A human previews and leaves send for a later step\n\n**On screen:** the agent transcript with the prompt (no colour or mood words), one finished still, and the Klaviyo image block settings (alt text and width). Blur the Brandiseer API key and any Klaviyo private key. Do not show a sent campaign, and do not show a fake video player in the guide."},"sections":[{"id":"overview","heading":"Overview","markdown":"**Brandiseer + Klaviyo (+ Cursor or Claude Cowork)**\n\n![Cover: an on-brand email hero ready to place in a Klaviyo image block](https://blog.brandiseer.com/use-case-assets/klaviyo-email-heroes/cover-klaviyo-email-heroes.png)\n\nBy the end of this guide you will have a repeatable way to make on-brand stills for Klaviyo emails. An agent in Cursor or Claude Cowork calls Brandiseer, gets an `imageUrl` for an email hero, a header still, or a promo image, and a person places that file in Klaviyo.\n\nBrandiseer owns the brand memory and the still. Klaviyo owns the template, the campaign, and the flow. Brandiseer does not open Klaviyo, does not upload into the image library by itself, and does not send the campaign or change a flow. A person downloads the file or copies `imageUrl`, then uses an image block (Import Image, upload, or Image Library) or uploads it under **Content > Images & brand > Images**. Optional Images API imports are documented only where Klaviyo's own developer pages describe them. An import lands the file in the library. It does not assign an image block, and it does not send.\n\n> People who brief stills inside Slack should use [Slack creative desk](/use-cases/slack-creative-desk). Recurring captions and Buffer scheduling should use [Social media automation](/use-cases/social-media-automation). Schedules and webhooks in Zapier, Make, or n8n should use [Always-on creative automation](/use-cases/always-on-creative-automation). Site heroes that live in Webflow should use [Webflow site visuals](/use-cases/webflow-site-visuals). HubSpot emails, landing pages, and ads should use [HubSpot campaign creatives](/use-cases/hubspot-campaign-creatives). This guide does not recreate any of those. It is Klaviyo email placement only."},{"id":"audience","heading":"Who it's for","markdown":"- Lifecycle, CRM, and email marketers who already send in Klaviyo and need a hero, a header still, or a promo image without opening a separate design tool for every campaign or flow\n- Agencies that keep one Brandiseer Brand ID per client and one Klaviyo account per client\n- Operators who can paste an `imageUrl` into a Klaviyo image block, or upload the file into the image library and then assign it\n\n**Ideal customer profile:** a team whose campaigns and flows already live in Klaviyo, whose brand already lives in Brandiseer, and whose missing piece is a brand-safe still plus a clear handoff into an image block or the image library."},{"id":"why-brandiseer","heading":"Why Brandiseer in this stack","markdown":"Klaviyo is where the email is built and sent. Cursor or Cowork is the agent that turns a brief into a layout. Brandiseer stores the logo and visual identity once, then applies that memory on every still. The prompt carries subject, layout, composition, and on-image text. It does not restate colours, fonts, mood, or visual style.\n\nA Klaviyo programme drifts when every hero is a one-off export from a general image tool. Brandiseer keeps the still on the same brand as the rest of the campaign. Klaviyo still decides which template receives the file, and a person decides when that email is sent.\n\nThis is a different job from the sibling guides:\n\n- [Slack creative desk](/use-cases/slack-creative-desk) is a request-and-return desk. A person writes a brief in Slack and an agent posts a still back in the thread.\n- [Social media automation](/use-cases/social-media-automation) writes captions and schedules posts with Buffer.\n- [Always-on creative automation](/use-cases/always-on-creative-automation) is the HTTP step in Zapier, Make, or n8n.\n- [Webflow site visuals](/use-cases/webflow-site-visuals) generates site stills and hands `imageUrl` to Webflow.\n- [HubSpot campaign creatives](/use-cases/hubspot-campaign-creatives) generates campaign stills and hands `imageUrl` to HubSpot.\n- This guide generates email heroes, headers, and promo stills and hands `imageUrl` to Klaviyo. Brandiseer does not push into Klaviyo and does not send campaigns.\n\n![Example strip: email hero, promo square, section background, and footer banner](https://blog.brandiseer.com/use-case-assets/klaviyo-email-heroes/example-strip.png)"},{"id":"stack","heading":"Stack","markdown":"| Layer | Tool | Role |\n| --- | --- | --- |\n| Brand visuals | Brandiseer MCP and/or REST v2 | Generate on-brand stills. MCP uses `Authorization: Bearer`. REST uses `X-API-Key: bds_...` |\n| Agent host (pick one) | Cursor | Read the email brief, call Brandiseer, return `imageUrl` and a placement note |\n| Agent host (pick one) | Claude Cowork | Same contract as Cursor for interactive email stills |\n| Email home | Klaviyo | Template image blocks and the image library. A person places the still. |\n\n![Stack diagram: Cursor or Cowork, Brandiseer, and Klaviyo](https://blog.brandiseer.com/use-case-assets/klaviyo-email-heroes/stack-diagram.png)\n\nYou only need one agent host. The Brandiseer contract is the same on both. Klaviyo has no Brandiseer app that drops a still into a template. The handoff is an image URL or a download. A person places it.\n\n**Brandiseer docs:** [Developers](https://brandiseer.com/developers) · [guide/docs](https://brandiseer.com/guide/docs) · [guide/image](https://brandiseer.com/guide/image) · [Settings → API](https://brandiseer.com/settings/api)\n\n**Klaviyo docs:** [Email template editor](https://help.klaviyo.com/hc/en-us/articles/4407911841435) · [Email image best practices](https://help.klaviyo.com/hc/en-us/articles/115005253688) · [Background images](https://help.klaviyo.com/hc/en-us/articles/115005255968) · [Dynamic images](https://help.klaviyo.com/hc/en-us/articles/4408810769307) · [Images API overview](https://developers.klaviyo.com/en/reference/images_api_overview) · [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url) · [Upload Image From File](https://developers.klaviyo.com/en/reference/upload_image_from_file)\n\nKlaviyo's API pages carry a `revision` date. The Upload Image From URL page fetched for this guide defaulted to `2026-07-15`. Call the path on the page you open, and send the `revision` header that page shows. Do not invent a neighbouring revision or a template-write path.\n\nEndpoint tables and HTTP contracts are in API reference at the end of this guide.\n\n### Klaviyo (placement, not generation)\n\nTwo practical paths. Use the first one unless you already have a private API key and only need the file in the library.\n\n1. **Image block or image library (default).** Download the file or copy `imageUrl`. In the template editor, drag an **image block** into the canvas. Klaviyo's editor lets you add the image from the Image Library, by uploading a JPEG, PNG, or GIF, by **Import Image** with an image URL, or as a Dynamic Image. The image library itself is **Content > Images & brand > Images**. Brandiseer stops at the URL. See [the template editor](https://help.klaviyo.com/hc/en-us/articles/4407911841435) and [email image best practices](https://help.klaviyo.com/hc/en-us/articles/115005253688).\n2. **Images API (optional library import).** When you already have a private key with `images:write`, import the public `imageUrl` with the call on [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url). A `201` puts the image in the account library (`hidden: false` so it shows there). It does not place the image in a template, and it does not send a campaign. See Setup stage 6.\n\nThis guide does not create campaigns, assign templates to campaign messages, update drag-and-drop templates, or call `send_campaign`. A person places the still and sends later, outside this workflow.\n\nA hero or header in this guide is a wide still in an image block at the top of the email, or a section background when text must sit on top of the picture. It is not the **header/link bar** block. That block is a logo plus navigation links. Klaviyo's editor article says Outlook can add a border to header/link bar elements, and suggests a logo image block plus a table when you need to avoid that. Do not drop a campaign hero into the header/link bar and call it placed."},{"id":"architecture","heading":"How it works","markdown":"Architecture, from email brief to a still sitting in a Klaviyo template:\n\n1. You store the brand once in Brandiseer (logo and reference visuals teach the look).\n2. The agent host (Cursor or Cowork) has Brandiseer MCP or REST, the Brand ID (`bds_c_...`), and the standing instructions in this guide.\n3. You name the slot: email hero or header, promo still, section background, or a short footer banner. The agent rewrites that brief into subject, layout, and on-image text, then sets `aspectRatio`, `resolution`, `mode`, and `useLogo` as fields.\n4. Brandiseer returns `imageUrl`. The agent reports the URL, the crop, the mode, a suggested alt text line, and a placement note (which template and which block). It does not claim the Klaviyo template changed.\n5. A person imports or uploads the file and assigns it in the template editor. They set alt text, the click link, and the display width. They leave the campaign unsent and the flow status unchanged. Optional API steps follow Klaviyo's Images API and stop at the library.\n\n![Workflow infographic: brief, Brandiseer still, imageUrl, Klaviyo library or Import Image, a person places the image](https://blog.brandiseer.com/use-case-assets/klaviyo-email-heroes/workflow-infographic.png)"},{"id":"prerequisites","heading":"What you need","markdown":"- Company website URL, if the brand is not in Brandiseer yet\n- Brandiseer account with at least one finished brand profile\n- API key (`bds_...`) from [Settings → API](https://brandiseer.com/settings/api) or [Developers](https://brandiseer.com/developers)\n- Brand ID (`bds_c_...`) for every brand the agent may call\n- Credits for the stills you actually generate (see the table in Limits & FAQ)\n- Cursor or Claude Cowork, with Brandiseer MCP or a way to call REST\n- A Klaviyo account you can edit\n- Access to the email template editor (a draft campaign, a flow email, or **Email Templates**) and to **Content > Images & brand > Images**\n- Optional, only for the Images API: a Klaviyo private API key with the `images:write` scope, in the agent secret store. Requests use `Authorization: Klaviyo-API-Key` plus a `revision` header, as on [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url). This key is not the Brandiseer key. Klaviyo's remote MCP is Owner, Admin, or Manager only. This guide does not require that MCP"},{"id":"setup","heading":"Setup","markdown":"### Stage 1: Add your brand on Brandiseer\n\n1. Go to [brandiseer.com](https://brandiseer.com). In the homepage input, enter your company website URL and click **Try My Brand**.\n2. Wait about one minute while Brandiseer analyses the site and picks a logo and visuals.\n3. Review those visuals carefully. They teach Brandiseer your look. Every later Klaviyo still is influenced by what you leave here.\n4. Remove anything off-brand (partner logos, stock, irrelevant screenshots). Add campaign creatives or product photography that match the look you want.\n5. Click **Add Brand**, sign up if prompted, then wait about 30 seconds for the brand profile to finish.\n\nAgencies repeat this once per client. Do not point two Klaviyo accounts at one Brand ID.\n\n### Stage 2: API key and Brand ID\n\n1. Open [brandiseer.com/developers](https://brandiseer.com/developers) or [Settings → API](https://brandiseer.com/settings/api).\n2. Create an API key (`bds_...`). Put it in the agent host's secret store. Do not paste it into a Klaviyo template, a campaign, Slack, or a git repo.\n3. Copy the Brand ID (`bds_c_...`).\n4. Confirm the key with `GET https://brandiseer.com/api/v1/credits` and `GET https://brandiseer.com/api/v1/brands`, header `X-API-Key`. The credits JSON includes `credits`. The brands list includes each brand `id`.\n5. Optional reachability check, no key required: `GET https://brandiseer.com/api/v1/health` returns `{ \"status\": \"ok\" }`.\n\nRead [guide/docs](https://brandiseer.com/guide/docs) and [guide/image](https://brandiseer.com/guide/image) once while you write the standing instructions. Those pages are the live contract if a field name ever moves.\n\n### Stage 3: Connect Brandiseer to the agent host\n\nUse Cursor or Cowork. One host is enough.\n\n**A. MCP**\n\n1. Add the Brandiseer MCP server at `https://brandiseer.com/api/mcp`.\n2. Authenticate with `Authorization: Bearer` and the API key, in the secret field your host provides.\n3. Confirm the tool list shows `brandiseer_list_brands`, `brandiseer_check_credits`, and `brandiseer_generate_image`. If a fourth Brandiseer tool appears, ignore it until [guide/docs](https://brandiseer.com/guide/docs) documents it.\n\n**B. REST**\n\n1. On [Developers](https://brandiseer.com/developers), open **View Docs** and use **Copy for LLM** if you want the reference inside the session.\n2. Tell the agent to prefer `POST https://brandiseer.com/api/v2/generate` or `POST https://brandiseer.com/api/v2/generate/async` with `X-API-Key`.\n3. If Design mode times out, switch that call to async and poll `GET https://brandiseer.com/api/v2/jobs/:jobId` every 3 to 5 seconds.\n\n### Stage 4: Save the standing instructions\n\n1. Paste the **System prompt** from this guide into the Cursor rule or Cowork instructions that will run email stills.\n2. Fill the defaults the prompt asks for: Brand ID, default crops per slot, resolution, mode, and whether `useLogo` is on when the brief is silent.\n3. Ask the agent to call `brandiseer_list_brands` (or `GET /api/v1/brands`) and confirm the Brand ID exists before the first paid still.\n\n### Stage 5: Smoke test a hero in an image block\n\n1. Ask for one email hero with a layout-only brief (the Spring hero in Example flows).\n2. Confirm the agent checked the brand, avoided colour and mood words, and returned `imageUrl` plus crop, mode, and a placement note.\n3. In Klaviyo, open a **draft** campaign or an unsent template. Drag an **image block** to the top of the canvas. Add the still by **Import Image** (paste `imageUrl`), by uploading the downloaded file, or by choosing it from the Image Library after you have uploaded it under **Content > Images & brand > Images**.\n4. Set alt text, a link address if the hero should be clickable, alignment, and width. Klaviyo recommends a 600px content width, full-width images about 600 to 1000px wide and under 2000px tall, and files around 1MB or smaller. The editor accepts up to 10MB. A large Brandiseer still can be inserted and then resized in the block. Klaviyo's own tip for crispness is to use a larger source and display it smaller.\n5. Use **Preview & test**. For a campaign or a list, segment, price-drop, or date-triggered flow, search a profile. For a metric-triggered flow, preview by the triggering event. Leave the campaign unsent. Do not change a flow's status.\n6. Send a second brief that only says \"make the hero premium and moody\". The agent should ask what is physically in the frame instead of generating.\n\nIf the hero must sit behind a Klaviyo text block and button, use a section background instead of baking the headline into the image. That path is in the next stage. Prefer the image block when inbox support matters: Klaviyo documents that Outlook for Windows does not support background images, and that Yahoo Mail and AOL have partial support.\n\n### Stage 6: Optional image library import (Images API)\n\nSkip this stage if people will import or upload by hand. Use it only when a private key already exists and the still must appear in the library before someone opens the template.\n\n1. Create the key with the `images:write` scope. Authentication is documented on [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url) and the [API overview](https://developers.klaviyo.com/en/reference/api-overview): header `Authorization: Klaviyo-API-Key `, header `revision` (use the default printed on the endpoint page; this guide saw `2026-07-15`), and `accept` plus `content-type` of `application/vnd.api+json`. This is not the Brandiseer key.\n2. Generate the still in Brandiseer first. Klaviyo has to be able to fetch `import_from_url`. The same page limits that import to jpeg, png, and gif, and to 5MB. If `imageUrl` is not public, the file is larger than 5MB, or Klaviyo rejects the format, stop the API call. Download the file and upload it in the template editor instead (10MB there; JPEG, PNG, GIF, and WebP that Klaviyo converts to PNG, except animated WebP).\n3. Import with the documented call: `POST https://a.klaviyo.com/api/images`. Rate limits on that page: burst `3/s`, steady `100/m`, daily `100/d`. Body:\n\n```json\n{\n \"data\": {\n \"type\": \"image\",\n \"attributes\": {\n \"import_from_url\": \"https://...\",\n \"name\": \"spring-email-hero\",\n \"hidden\": false\n }\n }\n}\n```\n\n`import_from_url` is required. `name` defaults to the filename if you omit it. If the name already exists, Klaviyo adds a suffix. Keep `hidden` false so the file shows in the asset library. A data URI is also accepted on that page. Prefer the public `imageUrl` when it meets the 5MB and format rules.\n\n4. A `201` body includes `data.id` and `data.attributes` (`name`, `image_url`, `format`, `size`, `hidden`, `updated_at`). The `links.self` value looks like `https://a.klaviyo.com/api/images/{id}/`. Confirm with `GET https://a.klaviyo.com/api/images` (the overview's list example) using the same key and `revision` header. The Klaviyo-hosted `image_url` is what you then pick in the template. It is not yet inside an image block.\n5. If you already have the file on disk and the URL import failed, the file upload is `POST https://a.klaviyo.com/api/image-upload` with `content-type: multipart/form-data`, form fields `file` (required), optional `name`, and optional `hidden`. The overview's example uses the same `Authorization` and `revision` headers. Same 5MB jpeg, png, or gif limit. A person still places the file.\n6. Open the draft template, drag an image block, and choose the image from the Image Library. Do not send the campaign in the smoke test.\n\nThe editor's automatic compression review (compare original and compressed, or an upload setting of Compare, Use originals, or Use compressed) applies when a person uploads in the product. It is not part of the API body above. GIFs are not compressed by that tool.\n\n### Stage 7: Section background, when text must sit on the image\n\nSkip this unless the brief needs Klaviyo text or buttons on top of the still. Klaviyo recommends this over a single image full of text, because recipients who block images, and people using screen readers, still get the text. Background images fail in some inboxes (see Limits & FAQ), so also set a section colour close to the image.\n\n1. Download the still. The background article does not describe an Import URL field. It says: open the section **Styles** tab, find **Background**, click **+**, then **Browse Image Library** and upload.\n2. Add a text block and, if you need one, a button, in that section. Leave those words out of the Brandiseer prompt. Tell the agent \"empty region\" instead.\n3. In **Format**, pick Original size, Fit, Fill, or Tile. **Display on** is Content or Section, which chooses whether the image stays in the content width or spans the section.\n4. Turn **Section color** on and pick a fallback colour. For a whole-template background, use the template **Styles** tab, click **+**, and choose a library image or upload. Set a template background colour as well. Full steps: [background images](https://help.klaviyo.com/hc/en-us/articles/115005255968).\n5. Preview. Do not send."},{"id":"prompting-rules","heading":"Prompting rules for Brandiseer images","markdown":"When the agent builds `prompt`:\n\n- Keep subject, layout, composition, and on-image text (what the words say and where they sit).\n- Never send brand colours, fonts, mood, or visual style. Brand memory already applies those. Style words fight the brand and produce off-brand stills.\n- Put crop in `aspectRatio`, quality in `mode`, pixel size in `resolution`, and logo on/off in `useLogo`. Those are body fields, not prompt prose.\n- Map the Klaviyo slot to a documented ratio. Email hero, header, and section background: `16:9`. Promo square: `1:1`. A card-like block in the email: `4:3`. A short footer banner: `16:9`, then the person sets a shorter display height or crops a rectangle in the image block. Brandiseer does not offer a 600px-wide email ratio. Portrait `9:16` is a poor default inside a 600px column. Use it only when the brief explicitly asks for a tall still.\n- Prefer `design` for finished email stills. `fast` is the API default if you omit `mode`, and it is the right fallback if a design job fails once.\n- Prefer `1K` or `2K`. Klaviyo asks for files around 1MB, allows 10MB in the editor, and allows 5MB on the Images API. `4K` is optional and easier to reject. PNG is the better editor choice when the still contains text. Klaviyo says PNG displays best across devices for images that contain text.\n- Set `useLogo` true only when the brief asked for a logo (or your default says so). Headlines that a Klaviyo text block will render should stay off the image. Say \"empty region\" for that area instead of describing a font.\n- Full rules: [Prompt compatibility](https://brandiseer.com/guide/image)."},{"id":"system-prompts","heading":"System prompt","markdown":"Paste this into Cursor or Cowork as the standing instructions for Klaviyo email stills. Replace the placeholders before the first generate.\n\n```text\nYou generate on-brand email heroes, headers, and promo stills for Klaviyo.\nBrandiseer returns an image URL. You do not push pixels into Klaviyo, and\nyou do not send a campaign or change a flow.\n\nBrandiseer:\n- MCP: https://brandiseer.com/api/mcp with Authorization: Bearer.\n Tools you may call: brandiseer_list_brands, brandiseer_check_credits,\n brandiseer_generate_image. Do not invent tool names.\n- REST: X-API-Key: bds_... (secret store only).\n Prefer POST https://brandiseer.com/api/v2/generate\n or POST https://brandiseer.com/api/v2/generate/async\n then poll GET https://brandiseer.com/api/v2/jobs/:jobId every 3 to 5 seconds\n until data.status is done or failed, or about 10 minutes have passed.\n- Live contract: https://brandiseer.com/guide/docs and\n https://brandiseer.com/guide/image\n\nDefaults for this account (fill in once):\n- Brand ID: bds_c_...\n- Email hero, header, and section background aspectRatio: 16:9\n- Promo square aspectRatio: 1:1\n- mode: design\n- resolution: 2K (use 1K if a 5MB Klaviyo API import is in play)\n- useLogo when the brief is silent: false\n- Multi-brand map, if any: brand name to bds_c_...\n\nOn every request:\n1. Resolve brandId from the brief or the default. If more than one brand\n exists and the brief does not name one, ask. Never fall through to\n another client's Brand ID.\n2. Check credits before a batch (brandiseer_check_credits or\n GET https://brandiseer.com/api/v1/credits). A single still can proceed\n if the last known balance covers the mode and resolution in the table\n you were given. On 402, stop.\n3. Rewrite the brief into subject, layout, composition, and on-image text.\n Strip colours, fonts, mood, and visual style. If stripping leaves no\n physical subject, ask what is in the frame. Do not generate.\n4. Choose aspectRatio from the slot. Put resolution, mode, and useLogo in\n API fields, not in the prompt. Do not invent a 600px email ratio.\n5. Generate one still. Return imageUrl, aspectRatio, mode, resolution,\n useLogo, a one-line alt text suggestion, and a placement note:\n image block (hero, header, promo, or footer) or section background.\n6. Do not tell the user the Klaviyo template changed unless they confirm\n they placed the file. Do not send, schedule, or publish.\n\nKlaviyo, only when the human already supplied a private key and asked\nto import the file into the image library:\n- Authorization: Klaviyo-API-Key, the private key. Never the Brandiseer key.\n- revision header: copy it from\n https://developers.klaviyo.com/en/reference/upload_image_from_url\n- POST https://a.klaviyo.com/api/images\n content-type application/vnd.api+json\n data.type = image\n data.attributes.import_from_url = the Brandiseer imageUrl\n data.attributes.hidden = false\n- jpeg, png, or gif, maximum 5MB, scope images:write.\n If the file is larger or the format is rejected, tell the human to\n upload it in the template editor. Do not invent a workaround URL.\n- A 201 means the library has the image. It does not mean an image\n block was filled. A person still places it.\n- File upload, only if they already have the bytes:\n POST https://a.klaviyo.com/api/image-upload as multipart form file.\n Same size and format limits. Read the Upload Image From File page.\n- Do not call campaign send, template update, or flow update tools.\n\nOut of scope:\n- Slack replies, Buffer scheduling, and Zapier, Make, or n8n scenarios.\n- Webflow site placement and HubSpot files, pages, or ads.\n- Legal approval of claims, prices, or offers printed on the image.\n- GET https://brandiseer.com/api/v1/usage (browser session only).\n```\n\n### Prompt rewriter\n\nUse this when a brief arrives as messy notes. It does not call Brandiseer. It only cleans text before you put it in `prompt`. The word list is a starting filter, not an official dictionary. If a phrase still describes colour, type, mood, or look, delete it by hand.\n\n```javascript\n// Local rewriter for a Cursor or Cowork helper script.\n// Keeps subject, layout, composition, and on-image text.\n// Strips colour, type, mood, and visual-style language.\n\nconst STYLE_WORDS =\n /\\b(colou?rs?|palette|hex|fonts?|typefaces?|typography|serif|sans-serif|moods?|vibes?|aesthetics?|minimalist|luxury|playful|cinematic|pastel|neon|gradients?|moody|elegant|premium|on-brand)\\b/gi;\n\nconst SLOT_TO_RATIO = {\n hero: \"16:9\",\n header: \"16:9\",\n banner: \"16:9\",\n footer: \"16:9\",\n section: \"16:9\",\n background: \"16:9\",\n \"16:9\": \"16:9\",\n promo: \"1:1\",\n square: \"1:1\",\n \"1:1\": \"1:1\",\n card: \"4:3\",\n \"4:3\": \"4:3\",\n portrait: \"9:16\",\n \"9:16\": \"9:16\",\n};\n\nfunction rewriteBrandiseerPrompt(input) {\n const headline = String(input.headline || \"\").trim();\n const subject = String(input.subject || input.brief || \"\").trim();\n const slotKey = String(input.slot || input.crop || \"\").trim().toLowerCase();\n const aspectRatio = SLOT_TO_RATIO[slotKey] || \"\";\n\n let prompt = [subject, headline ? `On-image text: \"${headline}\".` : \"\"]\n .filter(Boolean)\n .join(\" \");\n\n prompt = prompt\n .replace(/#[0-9a-f]{3,8}\\b/gi, \" \")\n .replace(STYLE_WORDS, \" \")\n .replace(/\\s+/g, \" \")\n .trim();\n\n return {\n prompt,\n aspectRatio,\n needsSubject: prompt.length < 12 || !aspectRatio,\n };\n}\n```\n\nIf `needsSubject` is true, ask the human for a subject and a slot. Do not POST."},{"id":"add-ons","heading":"Add-ons","markdown":"Add these after the hero smoke test passes. They do not change Brandiseer's image contract, and they do not give Brandiseer a send button.\n\n### Approval before send\n\nAfter `imageUrl` is in the image block or on the section, a named reviewer uses **Preview & test**. Only then may someone schedule or send, in Klaviyo, as a separate step. Until that happens, leave the campaign as a draft and leave flow emails unreleased. Brandiseer does not approve legal claims, prices, or offers.\n\n### One brand per Klaviyo account\n\nKeep a table: Klaviyo account name, private-key secret name (only if you use stage 6), and `bds_c_...`. Require an account name on every brief when more than one account exists. If the name misses, stop and list the accounts you configured. Confirm Brand IDs with `GET /api/v1/brands`. Never fall through to another client's Brand ID or another account's key.\n\n### Credit soft-limit\n\nWhen `credits` is under a threshold you choose (for example 40), switch new email stills to `mode: fast` and `resolution: 1K`, or skip them. Fast at 1K costs 4 credits. An explicit \"run anyway\" from the human can override the skip. The threshold is yours, not a Brandiseer default.\n\n### Placement log\n\nKeep a short note next to the work: campaign or flow name, template, slot, `brandId`, `mode`, `aspectRatio`, `resolution`, `imageUrl`, and whether it was imported into an image block or uploaded for a section background. Brandiseer does not write this log. Klaviyo does not send it back to Brandiseer.\n\n### Reuse the block\n\nWhen the hero image block looks right, a person can save that block or section with the star icon in the template editor. Klaviyo calls this universal content. Later templates can insert it from the Universal tab. Edits can be applied to every copy. That save is a Klaviyo editor action. Brandiseer does not sync it. See the universal content section of the [template editor guide](https://help.klaviyo.com/hc/en-us/articles/4407911841435).\n\n### Dynamic image (not the default still)\n\nA Brandiseer `imageUrl` is one still for this send. Klaviyo's Dynamic Image option is a different feature: a personalisation tag from profile or event data, pasted into **Select image > Dynamic Image**. Use it only when that variable already exists. The help article shows filters such as `{{ event.image_url|missing_product_image }}` and a `default` filter with your own backup URL. Read [How to insert a dynamic image](https://help.klaviyo.com/hc/en-us/articles/4408810769307) before you paste a tag. This guide does not write profile properties and does not invent event paths.\n\n### Handoff to the sibling guides\n\n- Stills requested in Slack, returned in a thread: [Slack creative desk](/use-cases/slack-creative-desk).\n- Captions and a Buffer schedule: [Social media automation](/use-cases/social-media-automation).\n- A Zapier, Make, or n8n trigger that should deliver `imageUrl` on a schedule: [Always-on creative automation](/use-cases/always-on-creative-automation).\n- A homepage hero that lives in Webflow: [Webflow site visuals](/use-cases/webflow-site-visuals).\n- An email header, landing page, or ad that lives in HubSpot: [HubSpot campaign creatives](/use-cases/hubspot-campaign-creatives).\n\nDo not embed Buffer, a Slack desk, an always-on scenario, Webflow, or HubSpot inside this Klaviyo guide.\n\n### Optional motion (not the email MVP)\n\nMost inboxes strip embedded video. Klaviyo's video block does not play inside the email. You paste a YouTube, Vimeo, TikTok, or other hosted video URL, and a click opens a new tab. YouTube can supply a thumbnail. Other hosts need a thumbnail you upload. That thumbnail can be a Brandiseer still. The video URL is yours.\n\nBrandiseer video is a separate contract. Generate the still first, then send its public `imageUrl` to `POST https://brandiseer.com/api/v2.1/video/generate`. Poll `GET https://brandiseer.com/api/v2.1/video/jobs/:jobId`. Video jobs use `status` `completed` and a `videoUrl`, which is different from image jobs (`done` and `imageUrl`). Read [guide/video](https://brandiseer.com/guide/video) for tier, duration, and resolution before you enable this. Video credits are per second and are not the still table below. A video failure does not undo the still. Leave this off unless the brief explicitly asks to animate, and still do not send the campaign from this guide."},{"id":"limits-and-faq","heading":"Limits & FAQ","markdown":"### Does Brandiseer update Klaviyo templates or send campaigns?\n\nNo. Brandiseer returns `imageUrl`. A person imports that URL into an image block, uploads the file, or picks it from the image library, then sets alt text and width. A library import through the Images API only stores the file. It does not assign a block. Sending and flow changes stay in Klaviyo, after a person reviews the draft.\n\n### Is there a Brandiseer app inside Klaviyo?\n\nNo. There is no Brandiseer block in the template editor in this guide. Do not look for a native \"send to Klaviyo\" button on the Brandiseer side.\n\n### What if Klaviyo rejects the image?\n\nThe template editor supports JPEG, PNG, and GIF, and can convert a non-animated WebP to PNG. Editor uploads are capped at 10MB. Klaviyo recommends about 1MB or smaller, 72dpi, full-width images about 600 to 1000px wide and under 2000px tall, because large files load slowly. The Images API import and file upload are stricter: jpeg, png, or gif, maximum 5MB. If the API returns an error, or the file is over 5MB, download the still and upload it in the editor. Crop inside the image block if you need a circle, square, or custom rectangle. Klaviyo keeps the full image, so the crop can be changed later.\n\n### Which Klaviyo calls are in this guide?\n\nOnly calls confirmed on Klaviyo's public docs, and only at the level those pages describe:\n\n- Human placement: image block sources (Image Library, Upload Image, Import Image, Dynamic Image) on the [template editor](https://help.klaviyo.com/hc/en-us/articles/4407911841435) guide, file types and the 10MB cap on [email images](https://help.klaviyo.com/hc/en-us/articles/115005253688), library path **Content > Images & brand > Images** on that same article, and section or template backgrounds on [background images](https://help.klaviyo.com/hc/en-us/articles/115005255968).\n- Optional library import: `POST https://a.klaviyo.com/api/images` on [Upload Image From URL](https://developers.klaviyo.com/en/reference/upload_image_from_url), scope `images:write`, `revision` header, 5MB, jpeg/png/gif.\n- Optional file upload: `POST https://a.klaviyo.com/api/image-upload` on [Upload Image From File](https://developers.klaviyo.com/en/reference/upload_image_from_file) and the [Images API overview](https://developers.klaviyo.com/en/reference/images_api_overview).\n- Optional read-back: `GET https://a.klaviyo.com/api/images`, and the `self` link the create response returns.\n\nThis guide does not document a \"set the hero block\" endpoint. It does not call campaign send.\n\n### Can I use Klaviyo's own MCP?\n\nKlaviyo documents a remote MCP server at `https://mcp.klaviyo.com/mcp` for Owner, Admin, or Manager roles. See [Klaviyo MCP server](https://developers.klaviyo.com/en/docs/klaviyo_mcp_server). This guide does not connect it and does not depend on it. That page lists many tools, including `upload_image_from_url` (remote) and `upload_image_from_file` (not marked available on the remote server), plus template writers and `send_campaign`. Do not use those send or template tools for this workflow. If `upload_image_from_url` is actually exposed in your client, it is still only a library import. A person places the image block. Do not assume a tool fills a hero.\n\n### Where do the keys live?\n\nThe Brandiseer key (`bds_...`) and any Klaviyo private key live in the agent host's secret store. Never in a template, a campaign preview, a Slack message, a prompt you commit, or a workflow export in git. Rotate either key if it leaks. Poll a Brandiseer job with the same Brandiseer key that submitted it. Call Klaviyo with the Klaviyo key.\n\n### What do stills cost?\n\nCredits per still. Failures refund. Async submits deduct immediately and refund if the job fails.\n\n| Mode | 1K | 2K | 4K |\n| --- | --- | --- | --- |\n| Fast | 4 | 6 | 8 |\n| Design | 5 | 6 | 8 |\n| Pro | 6 | 8 | 10 |\n\n`402` means not enough credits. Pricing context: [brandiseer.com/pricing](https://brandiseer.com/pricing).\n\nKlaviyo's URL and file upload endpoints add their own cap: 100 uploads a day on the pages fetched for this guide, plus burst `3/s` and steady `100/m`. Hand uploads in the editor are not that API counter. If you are importing a large batch through the API, stay under the daily cap or switch the rest to the editor.\n\n### Why is the still off-brand?\n\nAlmost always because the prompt contained colours, fonts, mood, or visual style. Strip them and generate again. See [guide/image](https://brandiseer.com/guide/image).\n\n### Why does the crop look wrong in the email?\n\nBrandiseer aspect ratios are `1:1`, `16:9`, `9:16`, and `4:3`. Klaviyo emails are usually about 600px wide. Generate the hero at `16:9`, import it, then set the image block width and, if needed, crop a rectangle in the editor. Do not ask Brandiseer for a custom pixel size inside the prompt.\n\n### Why did the background disappear in Outlook?\n\nKlaviyo documents that Outlook for Windows does not support background images, and that Yahoo Mail and AOL have partial support. The section or template background colour shows instead. Put the offer in a text block, or place the still in an image block when that inbox matters.\n\n### How long can I poll?\n\nAbout 10 minutes, then the Brandiseer job expires. Poll every 3 to 5 seconds. Stop on `done` or `failed` as well. Do not start a second job for the same slot while the first is still open, or you will pay twice.\n\n### Which generate URL should new email work use?\n\n`POST /api/v2/generate` when the agent host waits long enough. `POST /api/v2/generate/async` when it does not. Legacy `POST /api/v1/generate` remains for older callers and only supports Fast and Pro via `proMode` boolean.\n\n### Does the agent approve claims on the image?\n\nNo. If the still has a price, a discount, or a legal line, a person reads it before send. Brandiseer does not review the claim.\n\n### Does deleting the library file remove it from the email?\n\nKlaviyo's image article says deleting an image from **Content > Images & brand > Images** does not remove it from templates that already use it. Do not treat a library delete as an unsend."},{"id":"demo","heading":"Demo / motion","markdown":"**Motion brief only. This is not an embed, and there is no walkthrough URL yet.**\n\n**Working title:** Klaviyo email heroes\n**Length:** 45 to 75 seconds\n\n**Story beats:**\n\n1. A person asks Cursor or Cowork for an email hero with a layout-only brief\n2. The agent calls Brandiseer (MCP or REST v2) and shows an on-brand still\n3. `imageUrl` is imported into a Klaviyo image block on a draft template\n4. Optional cut: the same file is uploaded as a section background, with a text block and button on top, still unsent\n5. A human previews and leaves send for a later step\n\n**On screen:** the agent transcript with the prompt (no colour or mood words), one finished still, and the Klaviyo image block settings (alt text and width). Blur the Brandiseer API key and any Klaviyo private key. Do not show a sent campaign, and do not show a fake video player in the guide."},{"id":"additional-1-example-flows","heading":"Example flows","markdown":"### Flow A: Email hero, placed in an image block\n\nThe brief: \"Email hero for the spring drop. Product on the left. Leave the right half empty. The heading will be a Klaviyo text block, not text on the image. No logo.\"\n\nThe agent selects the default `brandId`, sets `aspectRatio` to `16:9`, `mode` to `design`, `resolution` to `2K`, and `useLogo` to false, and returns `imageUrl` plus alt text such as \"Spring kit product, left side of the hero\". You open a draft campaign, drag an image block, choose **Import Image**, paste the URL, set alt text and width, and preview. You send later, after the heading and spacing look right.\n\n### Flow B: Promo square\n\nThe brief: \"Promo square for the same campaign. One product, centred. On-image text 20% off along the bottom. No logo.\"\n\nThe agent uses `1:1` and returns a second `imageUrl`. You add another image block under the hero. Two Design 2K stills cost 12 credits if both succeed. Failures refund.\n\n### Flow C: Section background with live text\n\nThe brief: \"Offer band background. Products along the bottom. Keep the top empty for a heading and a button I will add in Klaviyo. No words on the image.\"\n\nThe agent keeps on-image text out of the prompt. You download the file, open the section **Styles** tab, add the background from the image library, set a fallback section colour, then add a text block and a button. You tell the reviewer that Outlook for Windows will show the colour, not the picture.\n\n### Flow D: Credit check before a campaign set\n\nBefore Flow A and Flow B together, the agent calls `brandiseer_check_credits` or `GET https://brandiseer.com/api/v1/credits` and reads `credits`. Two Design 2K stills need 12 credits. If the balance is lower, it stops or switches the batch to `fast` at `1K` (4 credits each) only if you asked for that fallback. `GET /api/v1/usage` is a browser session endpoint. Do not call it from the agent.\n\n### Flow E: Style-only brief\n\nThe brief: \"Make the hero feel premium and moody.\"\n\nThe agent does not generate. It asks which email, what is physically in the frame, whether any words must appear on the image, and whether the logo is on. Colour, font, and mood stay out of the prompt.\n\n### Flow F: Header bar is not the hero\n\nThe brief: \"Put this in the header bar.\"\n\nThe agent does not treat the header/link bar block as the hero slot. It says that block is a logo and links, and it returns a `16:9` still for an image block at the top of the template unless you confirm you only wanted a small logo (`useLogo: true`, and a tighter crop you name)."},{"id":"additional-2-related-use-cases","heading":"Related use cases","markdown":"- [HubSpot campaign creatives](/use-cases/hubspot-campaign-creatives): on-brand stills placed in HubSpot emails, landing pages, and ads\n- [Webflow site visuals](/use-cases/webflow-site-visuals): on-brand stills placed in Webflow Assets or CMS image fields\n- [Always-on creative automation](/use-cases/always-on-creative-automation): Zapier, Make, or n8n calls Brandiseer REST and delivers `imageUrl` downstream\n- [Slack creative desk](/use-cases/slack-creative-desk): people request stills in Slack and get them back in-thread\n- [Social media automation](/use-cases/social-media-automation): on-brand images, captions, and Buffer scheduling"},{"id":"additional-3-links","heading":"Links","markdown":"| Resource | URL |\n| --- | --- |\n| Brandiseer | https://brandiseer.com |\n| Developers | https://brandiseer.com/developers |\n| API reference (guide/docs) | https://brandiseer.com/guide/docs |\n| Image prompt compatibility | https://brandiseer.com/guide/image |\n| Video prompting (optional motion) | https://brandiseer.com/guide/video |\n| MCP endpoint (agent hosts) | https://brandiseer.com/api/mcp |\n| API keys | https://brandiseer.com/settings/api |\n| Pricing / credits | https://brandiseer.com/pricing |\n| Klaviyo | https://www.klaviyo.com |\n| Klaviyo template editor | https://help.klaviyo.com/hc/en-us/articles/4407911841435 |\n| Klaviyo email images | https://help.klaviyo.com/hc/en-us/articles/115005253688 |\n| Klaviyo background images | https://help.klaviyo.com/hc/en-us/articles/115005255968 |\n| Klaviyo dynamic images | https://help.klaviyo.com/hc/en-us/articles/4408810769307 |\n| Klaviyo Images API overview | https://developers.klaviyo.com/en/reference/images_api_overview |\n| Klaviyo upload image from URL | https://developers.klaviyo.com/en/reference/upload_image_from_url |\n| Klaviyo upload image from file | https://developers.klaviyo.com/en/reference/upload_image_from_file |\n| Klaviyo API overview | https://developers.klaviyo.com/en/reference/api-overview |\n| Klaviyo MCP server | https://developers.klaviyo.com/en/docs/klaviyo_mcp_server |\n| Visual pack manifest | `assets/MANIFEST.md` |\n| Sibling: HubSpot campaign creatives | https://blog.brandiseer.com/use-cases/hubspot-campaign-creatives |\n| Sibling: Webflow site visuals | https://blog.brandiseer.com/use-cases/webflow-site-visuals |\n| Sibling: Always-on creative automation | https://blog.brandiseer.com/use-cases/always-on-creative-automation |\n| Sibling: Slack creative desk | https://blog.brandiseer.com/use-cases/slack-creative-desk |\n| Sibling: Social media automation | https://blog.brandiseer.com/use-cases/social-media-automation |"},{"id":"additional-4-source","heading":"Source","markdown":"Public Use case README for Klaviyo email heroes. Brandiseer MCP and REST v2 image generation from Cursor or Claude Cowork, then a person places `imageUrl` in a Klaviyo template image block or the image library. Aligned with [guide/docs](https://brandiseer.com/guide/docs) and [guide/image](https://brandiseer.com/guide/image) (23 September 2026). Klaviyo placement steps follow the public help centre and Images API pages linked above. Brandiseer does not push into Klaviyo and does not send campaigns. Distinct from Slack creative desk, Buffer social scheduling, Zapier, Make, or n8n always-on HTTP, Webflow site visuals, and HubSpot campaign creatives."},{"id":"api-reference","heading":"API reference","markdown":"Wiring reference for agents and HTTP modules. The sections above are the human path.\n\n### MCP (interactive stills in Cursor or Cowork)\n\nConnect `https://brandiseer.com/api/mcp` with `Authorization: Bearer` and the API key. The only Brandiseer tools this guide uses are:\n\n- `brandiseer_list_brands`\n- `brandiseer_check_credits`\n- `brandiseer_generate_image`\n\nDo not invent extra Brandiseer tool names. If the host needs explicit `mode`, `aspectRatio`, or async polling, use REST v2 below. Brandiseer MCP does not edit Klaviyo.\n\n### REST (prefer v2 images)\n\nSend `X-API-Key: bds_...` on every authenticated Brandiseer call. There is no official SDK. Any HTTP client the agent host can run is enough.\n\n| Call | What you get |\n| --- | --- |\n| `POST https://brandiseer.com/api/v2/generate` | Sync still. `200` body `{ \"imageUrl\", \"creditsUsed\" }`. Design mode often takes 40 to 70 seconds. |\n| `POST https://brandiseer.com/api/v2/generate/async` | `202` body `{ \"data\": { \"jobId\" } }` (ids look like `bds_job_...`). Credits are deducted when you submit. |\n| `GET https://brandiseer.com/api/v2/jobs/:jobId` | Poll every 3 to 5 seconds with the same API key. `data.status` becomes `done` or `failed`. Jobs expire after about 10 minutes. Failures refund credits. |\n| `POST https://brandiseer.com/api/v1/generate` | Legacy only. `proMode` boolean. Fast and Pro only. Prefer v2. |\n| `GET https://brandiseer.com/api/v1/credits` | JSON includes `credits`, the current balance for that key. |\n| `GET https://brandiseer.com/api/v1/brands` | Brands for the key. Each brand `id` looks like `bds_c_...`. |\n| `GET https://brandiseer.com/api/v1/health` | `{ \"status\": \"ok\" }`. No API key. |\n\nImage body fields: `brandId`, `prompt`, optional `aspectRatio` (`1:1`, `16:9`, `9:16`, `4:3`), `resolution` (`1K`, `2K`, `4K`), `mode` (`fast`, `design`, or `pro`; default `fast` if you omit it), `useLogo`.\n\nSync status codes you should branch on: `200` success, `400` bad body, `401` bad key, `402` not enough credits, `404` brand not found, `500` server error.\n\nDone job body: `{ \"data\": { \"status\": \"done\", \"imageUrl\", \"creditsUsed\", \"referenceImage\" } }`. Hand `data.imageUrl` to the person placing it in Klaviyo. Failed job body: `{ \"data\": { \"status\": \"failed\", \"error\": { \"code\", \"message\" } } }`.\n\nCursor and Cowork can wait on a sync Design call when the session allows it. If the HTTP client times out under about 60 seconds, use async and poll. Do not point Klaviyo at the Brandiseer MCP URL.\n\n### Field mapping\n\n| Incoming field | API | Rule |\n| --- | --- | --- |\n| Slot (hero, header, promo, section, footer) | `aspectRatio` | Hero, header, section, footer: `16:9`. Promo square: `1:1`. In-email card: `4:3`. Portrait only if the brief asks: `9:16`. |\n| headline | inside `prompt` only | On-image text and placement. Not a separate body field. Leave it out when a Klaviyo text block will set the headline. |\n| brandId | `brandId` | `bds_c_...`. Required. |\n| mode | `mode` | `fast`, `design`, or `pro`. Omit and the API uses `fast`. Prefer `design` for email stills. |\n| useLogo | `useLogo` | `true` or `false`. |\n| subject or brief | `prompt` | After the rewriter. If the cleaned text has no subject, do not call Brandiseer. |\n| resolution | `resolution` | `1K`, `2K`, or `4K`. Prefer `2K` or `1K` when Klaviyo's 5MB API limit or 1MB inbox guidance applies. |\n\n### Example JSON\n\nUse this body for both sync and async. Only the URL and the response change.\n\n```json\n{\n \"brandId\": \"bds_c_...\",\n \"prompt\": \"Wide email hero. Product centred on the left third. Empty right half for a headline the email will set in a Klaviyo text block. No on-image text.\",\n \"aspectRatio\": \"16:9\",\n \"resolution\": \"2K\",\n \"mode\": \"design\",\n \"useLogo\": false\n}\n```\n\nSync: `POST https://brandiseer.com/api/v2/generate`. A Design 2K still costs 6 credits, so a success body looks like:\n\n```json\n{\n \"imageUrl\": \"https://...\",\n \"creditsUsed\": 6\n}\n```\n\nAsync: `POST https://brandiseer.com/api/v2/generate/async`. HTTP `202`:\n\n```json\n{\n \"data\": {\n \"jobId\": \"bds_job_...\"\n }\n}\n```\n\nPoll `GET https://brandiseer.com/api/v2/jobs/bds_job_...` with the same `X-API-Key`. When it finishes:\n\n```json\n{\n \"data\": {\n \"status\": \"done\",\n \"imageUrl\": \"https://...\",\n \"creditsUsed\": 6,\n \"referenceImage\": null\n }\n}\n```\n\nWhen it fails (credits are refunded):\n\n```json\n{\n \"data\": {\n \"status\": \"failed\",\n \"error\": {\n \"code\": \"...\",\n \"message\": \"...\"\n }\n }\n}\n```\n\nIgnore `referenceImage` for delivery. Klaviyo gets `imageUrl` (or a file you downloaded from it), pasted or uploaded by a person.\n\nSlot prompts that stay layout-only:\n\n| Slot | aspectRatio | Prompt |\n| --- | --- | --- |\n| Email hero or header | `16:9` | Wide email hero. Product centred on the left third. Empty right half for a headline the email will set in a Klaviyo text block. No on-image text. |\n| Promo square | `1:1` | Square promo. Single product in the centre. On-image text: \"20% off\" along the bottom edge. Open space above the product. |\n| Section background | `16:9` | Section background. Product cluster along the bottom edge. Upper two thirds empty for a Klaviyo heading and button. No on-image text. |\n| Footer banner | `16:9` | Short landscape banner. Product left of centre. On-image text: \"Spring kits\" in the right third. |"}],"actions":{"tryBrandiseer":"https://brandiseer.com","createApiKey":"https://brandiseer.com/settings/api","developerDocs":"https://brandiseer.com/developers","mcpEndpoint":"https://brandiseer.com/api/mcp"},"representations":{"html":"https://blog.brandiseer.com/use-cases/klaviyo-email-heroes","markdown":"https://blog.brandiseer.com/use-cases/klaviyo-email-heroes/agent.md","json":"https://blog.brandiseer.com/use-cases/klaviyo-email-heroes/guide.json"}}