{"schemaVersion":"1.0.0","kind":"brandiseer.use-case","id":"shopify-product-visuals","canonicalUrl":"https://blog.brandiseer.com/use-cases/shopify-product-visuals","contentHash":"28fc05bb375b4d6f2994d0091a70c29161f88d8f04d11ab267f43dc3e823e168","metadata":{"title":"Shopify product visuals","outcome":"An agent generates on-brand PDP heroes, lifestyle stills, collection cards, and promo tiles with Brandiseer; a person places imageUrl in Shopify Files, product media, or theme sections. Brandiseer does not push into Shopify Admin and does not publish the storefront.","category":"ecommerce","featured":true,"timeEstimate":"~25 to 40 min setup","methods":["MCP","REST"],"hosts":["Cursor","Cowork"],"image":"https://blog.brandiseer.com/use-case-assets/shopify-product-visuals/cover-shopify-product-visuals.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":"Shopify","role":"Files, product media, collection images, and theme sections. A person places the still.","href":"https://www.shopify.com"},{"name":"Cursor","role":"Agent host for Brandiseer MCP or REST"},{"name":"Claude Cowork","role":"Agent host for Brandiseer MCP or REST"}],"workflow":{"audience":"- Ecommerce and merchandising teams whose catalogue already lives in Shopify and who need a PDP hero, extra lifestyle frames, a collection image, or a theme promo tile without opening a separate design tool for every product\n- Agencies that keep one Brandiseer Brand ID per client and one Shopify store per client\n- Operators who can download an `imageUrl` and upload it in Shopify Admin, or paste that URL into the product media control Shopify's help page calls **Add from URL**\n\n**Ideal customer profile:** a team whose products, collections, and theme already live in Shopify, whose brand already lives in Brandiseer, and whose missing piece is a brand-safe still plus a clear handoff into Files, product media, a collection image, or a theme section.","rationale":"Shopify is where the product page, the collection, and the theme are built. Cursor or Cowork is the agent that turns a merch 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 Shopify catalogue drifts when every PDP image is a one-off export from a general image tool. Brandiseer keeps the still on the same brand as the rest of the range. Shopify still decides which product, collection, or section receives the file, and a person decides when that change is saved on a live product or published theme.\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- [Klaviyo email heroes](/use-cases/klaviyo-email-heroes) generates email heroes and hands `imageUrl` to Klaviyo.\n- This guide generates PDP heroes, lifestyle stills, collection cards, and promo tiles and hands `imageUrl` to a person who places them in Shopify. Brandiseer does not push into Shopify Admin and does not publish the storefront.\n\n![Example strip: PDP hero, lifestyle still, collection card, and promo tile](https://blog.brandiseer.com/use-case-assets/shopify-product-visuals/example-strip.png)","architecture":"Architecture, from product brief to a still sitting in Shopify:\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: PDP hero, lifestyle still, collection card, or promo tile. 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 one-line alt text suggestion, and a placement note (which product, collection, or theme section). It does not claim the Shopify admin changed.\n5. A person downloads the file or pastes the URL into **Add from URL**, then places it. They leave the published theme and any live product's main media alone until they have reviewed the still.\n\n![Workflow infographic: brief, Brandiseer still, imageUrl, a person uploads, a person places the image](https://blog.brandiseer.com/use-case-assets/shopify-product-visuals/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 Shopify store you can edit\n- Access to **Content > Files** and to **Products** for the product you will update\n- Access to **Products > Collections** if you will set a collection image. Shopify's legacy manual collections article says the Starter plan does not support collections. A higher plan is required for that slot.\n- Access to **Online Store** if you will place a promo tile. Duplicate the theme first. See [Duplicating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes). If the store already has 20 themes, that page says you must delete one before you can duplicate another. Deleting a theme is permanent.\n\nThis workflow does not need a Shopify API token.","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 Shopify still is influenced by what you leave here.\n4. Remove anything off-brand (partner logos, stock, irrelevant screenshots). Add product photography that matches 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 Shopify stores 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 Shopify product, a theme, 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 product 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 PDP still in product media\n\n1. Ask for one PDP 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. Open the URL in a browser before you place it.\n3. Download the file. Check it against the limits in Limits & FAQ before you upload. Rename it if the file name starts with a period, or if it ends with `pico`, `icon`, `thumb`, `testing`, `small`, `compact`, `medium`, `large`, or `grande`. Shopify's files article says those endings can be misread as image transforms, and Shopify then appends a suffix.\n4. In Shopify Admin, go to **Products** and open a product you are willing to edit. In **Media**, either click **Upload new** and select the file, or click **Select existing** and then **Add from URL** and paste `imageUrl`. You can also upload the file first under **Content > Files**, then come back and click **Select existing**.\n5. Look at the order. The first item is the main media, and Shopify displays that item on collection pages, the cart, the checkout, and the home page. If the new still is first and you are only proving the handoff, drag the previous main image back to the first position. That drag is the documented way to change the main media.\n6. Add alt text: open the media item, click **Add alt text**, enter a short description (Shopify recommends 125 characters or fewer; the maximum on that page is 512), click **Save alt text**, then close the preview. See [Adding alt text to media](https://help.shopify.com/en/manual/products/product-media/add-alt-text).\n7. Leave the product. Do not treat this smoke test as a catalogue launch.\n8. 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 **Add from URL** rejects the address, download the file and use **Upload new**. The help page names the control. It does not list hostnames Brandiseer must use.\n\n### Stage 6: Collection card\n\nSkip this stage unless the brief is a collection image. Shopify's product media article is about product media. A collection card here is the image on the collection itself.\n\nThe Starter plan does not support collections, per the legacy manual collections article. Upgrade before this stage if that is your plan.\n\nShopify's manual collections article says a new collections model is replacing the legacy manual and smart model, and that you can keep using manual collections until the new model is in your admin. Use the control the page you are on actually shows.\n\n**Collection that already has an image.** Follow [Editing collection details and layout](https://help.shopify.com/en/manual/products/collections/collection-layout):\n\n1. For a smoke test, duplicate a manual collection first. On [Legacy manual collections](https://help.shopify.com/en/manual/products/collections/manual-shopify-collection), **Duplicate** adds `(copy)` to the title, and the new collection is not on any sales channel until you publish it. Skip the sales-channel step. Click **Save**.\n2. Go to **Products > Collections** and open the copy.\n3. Hover over the image, then click **Change image**.\n4. Select the image, click **Done**, then click **Save**.\n\n**New collection, legacy create flow.** Follow [Legacy manual collections](https://help.shopify.com/en/manual/products/collections/manual-shopify-collection). In the **Collection image** section, click **Add image**. That article points image sizes at [Product media types](https://help.shopify.com/en/manual/products/product-media/product-media-types). Click **Save**. In **Sales channels**, leave Online Store off until a person has reviewed the still. The same article documents a future publish date if you need the collection to stay hidden until a set time. Do not add a menu link during the smoke test.\n\nProduct tiles on a collection page use each product's main media, not this collection image. If the brief is \"the thumbnail of the product inside the collection\", that is the PDP hero path in stage 5, and the first media item is what Shopify says it shows on collection pages.\n\n### Stage 7: Promo tile on a theme section\n\nSkip this stage unless the brief is a banner, slideshow, or other theme image. Do this on a duplicate theme so you are not editing the published theme.\n\n1. Duplicate the theme. From **Online Store**, open the actions menu on the theme and click **Duplicate**. The copy is named **Copy Of** plus the theme name. See [Duplicating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes).\n2. On that copy, click **Edit theme**. If the still belongs on a template other than the home page, use the **Home page** drop-down and select that template.\n3. In the sidebar, click the section or block that has an **Image** field. The section name depends on the theme. This guide does not invent a section called \"Promo tile\".\n4. In the **Image** field, click **Select image > Add images**, open the file from your computer, and click **Done**. The uploading-images article also offers **Explore free images** for Burst stock. Do not use Burst for this workflow.\n5. Click **Save** on the duplicate. Do not publish the theme.\n\nFull clicks: [Uploading images](https://help.shopify.com/en/manual/online-store/images/theme-images). That article says slideshow and background images should not contain text, because the theme can crop or move it. Put headlines in the theme's text settings. Tell the agent \"empty region\" for that area.\n\nThe same article says you can set a focal point so the important part stays in frame when the theme crops. One focal point applies everywhere that file is used. Open the image from **Content > Files**, the theme editor, or the product **Media** section, click the point (or drag the blue dot), and click **Save**. Focal points are documented for listed free-theme versions. Check the theme if it is a third-party theme.","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 Shopify slot to a documented Brandiseer ratio. PDP hero, lifestyle still, and collection card: `1:1`. Shopify's product media types page says a square product image of 2048 x 2048 px usually displays best, and that main images on collection pages should share one aspect ratio. Promo banner or slideshow: `16:9`, with no on-image text, because the theme article says theme crops can move text. A landscape card the human names as 4:3: `4:3`. Portrait only if the brief asks: `9:16`. Brandiseer does not offer a theme-specific crop. The theme or a focal point does the rest.\n- Prefer `design` for finished product stills. `fast` is the API default if you omit `mode`, and it is the right fallback if a design job fails once.\n- Prefer `2K` so a square still sits near the 2048 px size Shopify names. `1K` is the fallback when a file would miss a size cap. `4K` is optional. Check the downloaded file against the Shopify limit for that surface before upload.\n- Set `useLogo` true only when the brief asked for a logo (or your default says so). Headlines that a theme 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 Shopify product stills. Replace the placeholders before the first generate.\n\n```text\nYou generate on-brand PDP heroes, lifestyle stills, collection cards, and\npromo tiles for Shopify. Brandiseer returns an image URL. You do not push\npixels into Shopify Admin, and you do not publish the storefront.\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 store (fill in once):\n- Brand ID: bds_c_...\n- PDP hero, lifestyle still, and collection card aspectRatio: 1:1\n- Promo banner aspectRatio: 16:9\n- mode: design\n- resolution: 2K (use 1K if a file would miss Shopify's size cap)\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 theme pixel size.\n5. Generate one still. Return imageUrl, aspectRatio, mode, resolution,\n   useLogo, a one-line alt text suggestion (125 characters or fewer),\n   and a placement note: product media (name the product), collection\n   image (name the collection), or theme section on a duplicate theme.\n6. Do not tell the user the Shopify catalogue changed unless they confirm\n   they placed the file. Do not publish a theme, a product, or a collection.\n\nShopify placement is human only:\n- Files: Content > Files, Upload files. Public store files only.\n- Product media: Upload new, Select existing, or Select existing then\n  Add from URL. The first media item is the main image Shopify shows on\n  collection pages, cart, checkout, and the home page.\n- Collection image and theme Image fields: the person uploads a file.\n  Promo text belongs in the theme, not on the image, when the theme crops.\n- Do not call the Shopify Admin API. Do not invent API paths. Do not ask\n  for a Shopify token.\n\nOut of scope:\n- Slack replies, Buffer scheduling, and Zapier, Make, or n8n scenarios.\n- Webflow site placement, HubSpot files or ads, and Klaviyo email placement.\n- Prices, inventory, SKUs, and product descriptions.\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  pdp: \"1:1\",\n  hero: \"1:1\",\n  product: \"1:1\",\n  lifestyle: \"1:1\",\n  collection: \"1:1\",\n  card: \"1:1\",\n  square: \"1:1\",\n  \"1:1\": \"1:1\",\n  promo: \"16:9\",\n  banner: \"16:9\",\n  slideshow: \"16:9\",\n  tile: \"1:1\",\n  \"16:9\": \"16:9\",\n  landscape: \"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 PDP smoke test passes. They do not change Brandiseer's image contract, and they do not give Brandiseer a publish button.\n\n### Approval before the still is the main media\n\nAfter `imageUrl` is in the product **Media** section, a named reviewer checks the still and the alt text. Only then may someone drag it to the first position, where Shopify uses it on collection pages, the cart, the checkout, and the home page. Until that happens, keep the previous main image first. Brandiseer does not approve legal claims, prices, or offers.\n\nA theme promo stays on the duplicate until that same reviewer is happy. Publishing the theme is a separate admin action. This guide does not publish it.\n\n### One brand per Shopify store\n\nKeep a table: store name and `bds_c_...`. Require a store name on every brief when more than one store exists. If the name misses, stop and list the stores you configured. Confirm Brand IDs with `GET /api/v1/brands`. Never fall through to another client's Brand ID. There is no Shopify token in this table, because this guide does not call Shopify.\n\n### Credit soft-limit\n\nWhen `credits` is under a threshold you choose (for example 40), switch new product 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: store, product or collection or theme, slot, `brandId`, `mode`, `aspectRatio`, `resolution`, `imageUrl`, and whether it was uploaded, pasted with **Add from URL**, or left only in **Files**. Brandiseer does not write this log. Shopify does not send it back to Brandiseer.\n\n### Variant image (one frame, already on the product)\n\nShopify's variant article says you can assign one image to a variant, chosen from existing product images or uploaded from the device. Variants do not take 3D models or video. Add the lifestyle stills to the product gallery first, then assign one of those images to the variant. That assignment is a person in the **Variants** section. Read [Adding images to product variants](https://help.shopify.com/en/manual/products/product-media/add-images-variants) before you do it. Brandiseer does not map variants.\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- An email hero that lives in Klaviyo: [Klaviyo email heroes](/use-cases/klaviyo-email-heroes).\n\nDo not embed Buffer, a Slack desk, an always-on scenario, Webflow, HubSpot, or Klaviyo inside this Shopify guide.\n\n### Optional motion (not the product MVP)\n\nShopify product video is a different upload from a still. The product media types page lists video length up to 10 minutes, size up to 1 GB, resolution up to 4K (4096 x 2160 px), and file types `.mp4`, `.mov`, or `.webm`. YouTube or Vimeo links are the other option on that page. A theme must support video. This guide does not generate that file and does not publish it.\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 publish the product from this guide.","limitsAndFaq":"### Does Brandiseer update Shopify or publish the storefront?\n\nNo. Brandiseer returns `imageUrl`. A person uploads that file or pastes the URL into product media, sets a collection image, or adds it to a theme section on a duplicate theme. Saving a live product's main media, publishing a theme, and publishing a collection to a sales channel stay in Shopify, after a person reviews the still.\n\n### Is there a Brandiseer app inside Shopify?\n\nNo. There is no Brandiseer block in the theme editor in this guide. Do not look for a native \"send to Shopify\" button on the Brandiseer side.\n\n### What if Shopify rejects the image?\n\nCheck the page for the surface you are uploading to. The numbers are not identical across Shopify's help pages:\n\n- [Uploading and managing files](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads): images up to 20 MB and 25 megapixels. Formats JPEG, PNG, WEBP, HEIC, and GIF. Aspect ratio between 100:1 and 1:100. File names must not start with a period. Names that end in `pico`, `icon`, `thumb`, `testing`, `small`, `compact`, `medium`, `large`, or `grande` can be rewritten by Shopify's CDN.\n- [Product media types](https://help.shopify.com/en/manual/products/product-media/product-media-types): product and collection images up to 5000 x 5000 px, or 25 megapixels, and smaller than 20 MB. It names PNG as the best type for most product images, then JPEG, and also lists PSD, TIFF, BMP, GIF, SVG, HEIC, and WebP.\n- [Uploading images](https://help.shopify.com/en/manual/online-store/images/theme-images): says images uploaded to Shopify cannot exceed 20 megapixels or 20 megabytes. The same page also tells you to upload higher-resolution files up to 5000 x 5000 px or 25 megapixels for quality. If the theme editor rejects the file, reduce the pixel size. The page lists JPEG, progressive JPEG, PNG, GIF, HEIC, and WebP, and says PSD, TIFF, and BMP are accepted and converted to JPEG or PNG.\n\nPrefer `2K`, download the file, and confirm size before upload. If **Add from URL** fails, upload the file from your computer. A product can hold up to 250 media items.\n\n### Which Shopify actions are in this guide?\n\nOnly human steps confirmed on Shopify's public help pages:\n\n- **Content > Files**, **Upload files**, up to 20 files at a time, on [Uploading and managing files](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads).\n- Product **Media**: **Upload new**, drag and drop, **Select existing**, and **Select existing** then **Add from URL**, on [Adding product media](https://help.shopify.com/en/manual/products/product-media/add-media). Drag the chosen image to the first position only when it should be the main media.\n- Alt text: open the media, **Add alt text**, **Save alt text**, on [Adding alt text to media](https://help.shopify.com/en/manual/products/product-media/add-alt-text).\n- Collection image: **Add image** on create, from [Legacy manual collections](https://help.shopify.com/en/manual/products/collections/manual-shopify-collection), or hover and **Change image** from [Editing collection details and layout](https://help.shopify.com/en/manual/products/collections/collection-layout).\n- Theme image: duplicate the theme, **Edit theme** on the copy, **Select image > Add images**, **Save**, from [Uploading images](https://help.shopify.com/en/manual/online-store/images/theme-images) and [Duplicating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes).\n\nThis guide does not call Shopify's Admin API and does not list those paths. It does not publish the theme.\n\n### Can the agent use a Shopify token or Sidekick?\n\nNo. This workflow has no Shopify token. Shopify's collection layout page mentions Sidekick for sorting products in a collection. This guide does not use Sidekick to place images or to publish.\n\n### Where does the key live?\n\nOnly the Brandiseer key (`bds_...`) is in play. It lives in the agent host's secret store. Never in a product description, a theme setting, a Slack message, a prompt you commit, or a git repo. Rotate it if it leaks. Poll a Brandiseer job with the same key that submitted it.\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\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\nShopify's uploading-images article also says embedded colour profiles are removed when the image is displayed, and that browsers then assume sRGB. A shift after upload can be that removal. It is separate from an off-brand prompt.\n\n### Why does the crop look wrong on the storefront?\n\nBrandiseer aspect ratios are `1:1`, `16:9`, `9:16`, and `4:3`. Themes crop banners and collection grids. Generate the PDP and the collection image at `1:1`, and a wide promo at `16:9`, then set a focal point if the theme cuts the frame. Do not ask Brandiseer for a custom pixel size inside the prompt.\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 product 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 that image becomes the main media or the theme is published. Brandiseer does not review the claim.\n\n### Does uploading to Files publish the product?\n\nNo. **Content > Files** stores the file. Shopify's own caution is that those files are for public store use, so treat the file URL as public. Assignment to a product, a collection, or a theme section is a later human step.","demo":"**Motion brief only. This is not an embed, and there is no walkthrough URL yet.**\n\n**Working title:** Shopify product visuals\n**Length:** 45 to 75 seconds\n\n**Story beats:**\n\n1. A person asks Cursor or Cowork for a PDP hero with a layout-only brief\n2. The agent calls Brandiseer (MCP or REST v2) and shows an on-brand still\n3. `imageUrl` is uploaded to a product's Media section, and the previous main image stays first\n4. Optional cut: the same kind of still is placed on a duplicate theme section, still unpublished\n5. A human reviews alt text and leaves publish for a later step\n\n**On screen:** the agent transcript with the prompt (no colour or mood words), one finished still, and the Shopify Media section. Blur the Brandiseer API key. Do not show a published theme, and do not show a fake video player in the guide."},"sections":[{"id":"overview","heading":"Overview","markdown":"**Brandiseer + Shopify (+ Cursor or Claude Cowork)**\n\n![Cover: an on-brand product still ready to place in Shopify](https://blog.brandiseer.com/use-case-assets/shopify-product-visuals/cover-shopify-product-visuals.png)\n\nBy the end of this guide you will have a repeatable way to make on-brand stills for a Shopify store. An agent in Cursor or Claude Cowork calls Brandiseer, gets an `imageUrl` for a PDP hero, a lifestyle still, a collection card, or a promo tile, and a person places that file in Shopify.\n\nBrandiseer owns the brand memory and the still. Shopify owns the product, the collection, and the theme. Brandiseer does not open Shopify Admin, does not upload into Files or product media, and does not publish the theme or the product. A person downloads the file or copies `imageUrl`, then uploads it and assigns it. This guide does not call Shopify's Admin API and does not print Admin API paths.\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). Klaviyo email heroes should use [Klaviyo email heroes](/use-cases/klaviyo-email-heroes). This guide does not recreate any of those. It is Shopify product and storefront placement only."},{"id":"audience","heading":"Who it's for","markdown":"- Ecommerce and merchandising teams whose catalogue already lives in Shopify and who need a PDP hero, extra lifestyle frames, a collection image, or a theme promo tile without opening a separate design tool for every product\n- Agencies that keep one Brandiseer Brand ID per client and one Shopify store per client\n- Operators who can download an `imageUrl` and upload it in Shopify Admin, or paste that URL into the product media control Shopify's help page calls **Add from URL**\n\n**Ideal customer profile:** a team whose products, collections, and theme already live in Shopify, whose brand already lives in Brandiseer, and whose missing piece is a brand-safe still plus a clear handoff into Files, product media, a collection image, or a theme section."},{"id":"why-brandiseer","heading":"Why Brandiseer in this stack","markdown":"Shopify is where the product page, the collection, and the theme are built. Cursor or Cowork is the agent that turns a merch 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 Shopify catalogue drifts when every PDP image is a one-off export from a general image tool. Brandiseer keeps the still on the same brand as the rest of the range. Shopify still decides which product, collection, or section receives the file, and a person decides when that change is saved on a live product or published theme.\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- [Klaviyo email heroes](/use-cases/klaviyo-email-heroes) generates email heroes and hands `imageUrl` to Klaviyo.\n- This guide generates PDP heroes, lifestyle stills, collection cards, and promo tiles and hands `imageUrl` to a person who places them in Shopify. Brandiseer does not push into Shopify Admin and does not publish the storefront.\n\n![Example strip: PDP hero, lifestyle still, collection card, and promo tile](https://blog.brandiseer.com/use-case-assets/shopify-product-visuals/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 product brief, call Brandiseer, return `imageUrl` and a placement note |\n| Agent host (pick one) | Claude Cowork | Same contract as Cursor for interactive product stills |\n| Store | Shopify | Files, product media, collection images, and theme sections. A person places the still. |\n\n![Stack diagram: Cursor or Cowork, Brandiseer, and Shopify](https://blog.brandiseer.com/use-case-assets/shopify-product-visuals/stack-diagram.png)\n\nYou only need one agent host. The Brandiseer contract is the same on both. Shopify has no Brandiseer app that drops a still onto a product. 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**Shopify docs:** [Uploading and managing files](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads) · [Adding product media](https://help.shopify.com/en/manual/products/product-media/add-media) · [Product media types](https://help.shopify.com/en/manual/products/product-media/product-media-types) · [Adding alt text to media](https://help.shopify.com/en/manual/products/product-media/add-alt-text) · [Legacy manual collections](https://help.shopify.com/en/manual/products/collections/manual-shopify-collection) · [Editing collection details and layout](https://help.shopify.com/en/manual/products/collections/collection-layout) · [Uploading images (theme)](https://help.shopify.com/en/manual/online-store/images/theme-images) · [Duplicating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes)\n\nUse the clicks on those pages. Do not invent a neighbouring Admin API path. Shopify's help pages are the placement contract if a button label moves.\n\nEndpoint tables and HTTP contracts are in API reference at the end of this guide.\n\n### Shopify (placement, not generation)\n\nThree practical paths. A person does all of them. Use the one that matches the slot. Brandiseer stops at `imageUrl`.\n\n1. **Files, then the product or the theme (library).** In Shopify Admin, go to **Content > Files** and click **Upload files**. Select up to 20 files. Those files are then available in the admin, including as product media. This upload does not assign the file to a product, a collection, or a section. See [Uploading and managing files](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads). Shopify's caution on that page: only upload files intended for public access on the store. Do not upload confidential documents.\n2. **Product media (PDP hero and lifestyle stills).** On the product, the Media section can take **Upload new**, a drag-and-drop, **Select existing**, or **Add from URL** (open **Select existing**, then **Add from URL**, and paste `imageUrl`). The first media item is the featured, or main, media. Shopify says that main item is displayed on collection pages, the cart page, the checkout page, and the home page. See [Adding product media](https://help.shopify.com/en/manual/products/product-media/add-media).\n3. **Collection image or theme section (collection cards and promo tiles).** A collection card in this guide is the collection's own image, not a separate card field. A promo tile is an image on a theme section or block. Steps are in Setup stages 6 and 7. Neither step is a Brandiseer call.\n\nThere is no fourth path in this guide. Do not send a Shopify token to the agent. Do not publish the theme. Do not add the collection to sales channels during a smoke test."},{"id":"architecture","heading":"How it works","markdown":"Architecture, from product brief to a still sitting in Shopify:\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: PDP hero, lifestyle still, collection card, or promo tile. 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 one-line alt text suggestion, and a placement note (which product, collection, or theme section). It does not claim the Shopify admin changed.\n5. A person downloads the file or pastes the URL into **Add from URL**, then places it. They leave the published theme and any live product's main media alone until they have reviewed the still.\n\n![Workflow infographic: brief, Brandiseer still, imageUrl, a person uploads, a person places the image](https://blog.brandiseer.com/use-case-assets/shopify-product-visuals/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 Shopify store you can edit\n- Access to **Content > Files** and to **Products** for the product you will update\n- Access to **Products > Collections** if you will set a collection image. Shopify's legacy manual collections article says the Starter plan does not support collections. A higher plan is required for that slot.\n- Access to **Online Store** if you will place a promo tile. Duplicate the theme first. See [Duplicating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes). If the store already has 20 themes, that page says you must delete one before you can duplicate another. Deleting a theme is permanent.\n\nThis workflow does not need a Shopify API token."},{"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 Shopify still is influenced by what you leave here.\n4. Remove anything off-brand (partner logos, stock, irrelevant screenshots). Add product photography that matches 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 Shopify stores 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 Shopify product, a theme, 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 product 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 PDP still in product media\n\n1. Ask for one PDP 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. Open the URL in a browser before you place it.\n3. Download the file. Check it against the limits in Limits & FAQ before you upload. Rename it if the file name starts with a period, or if it ends with `pico`, `icon`, `thumb`, `testing`, `small`, `compact`, `medium`, `large`, or `grande`. Shopify's files article says those endings can be misread as image transforms, and Shopify then appends a suffix.\n4. In Shopify Admin, go to **Products** and open a product you are willing to edit. In **Media**, either click **Upload new** and select the file, or click **Select existing** and then **Add from URL** and paste `imageUrl`. You can also upload the file first under **Content > Files**, then come back and click **Select existing**.\n5. Look at the order. The first item is the main media, and Shopify displays that item on collection pages, the cart, the checkout, and the home page. If the new still is first and you are only proving the handoff, drag the previous main image back to the first position. That drag is the documented way to change the main media.\n6. Add alt text: open the media item, click **Add alt text**, enter a short description (Shopify recommends 125 characters or fewer; the maximum on that page is 512), click **Save alt text**, then close the preview. See [Adding alt text to media](https://help.shopify.com/en/manual/products/product-media/add-alt-text).\n7. Leave the product. Do not treat this smoke test as a catalogue launch.\n8. 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 **Add from URL** rejects the address, download the file and use **Upload new**. The help page names the control. It does not list hostnames Brandiseer must use.\n\n### Stage 6: Collection card\n\nSkip this stage unless the brief is a collection image. Shopify's product media article is about product media. A collection card here is the image on the collection itself.\n\nThe Starter plan does not support collections, per the legacy manual collections article. Upgrade before this stage if that is your plan.\n\nShopify's manual collections article says a new collections model is replacing the legacy manual and smart model, and that you can keep using manual collections until the new model is in your admin. Use the control the page you are on actually shows.\n\n**Collection that already has an image.** Follow [Editing collection details and layout](https://help.shopify.com/en/manual/products/collections/collection-layout):\n\n1. For a smoke test, duplicate a manual collection first. On [Legacy manual collections](https://help.shopify.com/en/manual/products/collections/manual-shopify-collection), **Duplicate** adds `(copy)` to the title, and the new collection is not on any sales channel until you publish it. Skip the sales-channel step. Click **Save**.\n2. Go to **Products > Collections** and open the copy.\n3. Hover over the image, then click **Change image**.\n4. Select the image, click **Done**, then click **Save**.\n\n**New collection, legacy create flow.** Follow [Legacy manual collections](https://help.shopify.com/en/manual/products/collections/manual-shopify-collection). In the **Collection image** section, click **Add image**. That article points image sizes at [Product media types](https://help.shopify.com/en/manual/products/product-media/product-media-types). Click **Save**. In **Sales channels**, leave Online Store off until a person has reviewed the still. The same article documents a future publish date if you need the collection to stay hidden until a set time. Do not add a menu link during the smoke test.\n\nProduct tiles on a collection page use each product's main media, not this collection image. If the brief is \"the thumbnail of the product inside the collection\", that is the PDP hero path in stage 5, and the first media item is what Shopify says it shows on collection pages.\n\n### Stage 7: Promo tile on a theme section\n\nSkip this stage unless the brief is a banner, slideshow, or other theme image. Do this on a duplicate theme so you are not editing the published theme.\n\n1. Duplicate the theme. From **Online Store**, open the actions menu on the theme and click **Duplicate**. The copy is named **Copy Of** plus the theme name. See [Duplicating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes).\n2. On that copy, click **Edit theme**. If the still belongs on a template other than the home page, use the **Home page** drop-down and select that template.\n3. In the sidebar, click the section or block that has an **Image** field. The section name depends on the theme. This guide does not invent a section called \"Promo tile\".\n4. In the **Image** field, click **Select image > Add images**, open the file from your computer, and click **Done**. The uploading-images article also offers **Explore free images** for Burst stock. Do not use Burst for this workflow.\n5. Click **Save** on the duplicate. Do not publish the theme.\n\nFull clicks: [Uploading images](https://help.shopify.com/en/manual/online-store/images/theme-images). That article says slideshow and background images should not contain text, because the theme can crop or move it. Put headlines in the theme's text settings. Tell the agent \"empty region\" for that area.\n\nThe same article says you can set a focal point so the important part stays in frame when the theme crops. One focal point applies everywhere that file is used. Open the image from **Content > Files**, the theme editor, or the product **Media** section, click the point (or drag the blue dot), and click **Save**. Focal points are documented for listed free-theme versions. Check the theme if it is a third-party theme."},{"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 Shopify slot to a documented Brandiseer ratio. PDP hero, lifestyle still, and collection card: `1:1`. Shopify's product media types page says a square product image of 2048 x 2048 px usually displays best, and that main images on collection pages should share one aspect ratio. Promo banner or slideshow: `16:9`, with no on-image text, because the theme article says theme crops can move text. A landscape card the human names as 4:3: `4:3`. Portrait only if the brief asks: `9:16`. Brandiseer does not offer a theme-specific crop. The theme or a focal point does the rest.\n- Prefer `design` for finished product stills. `fast` is the API default if you omit `mode`, and it is the right fallback if a design job fails once.\n- Prefer `2K` so a square still sits near the 2048 px size Shopify names. `1K` is the fallback when a file would miss a size cap. `4K` is optional. Check the downloaded file against the Shopify limit for that surface before upload.\n- Set `useLogo` true only when the brief asked for a logo (or your default says so). Headlines that a theme 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 Shopify product stills. Replace the placeholders before the first generate.\n\n```text\nYou generate on-brand PDP heroes, lifestyle stills, collection cards, and\npromo tiles for Shopify. Brandiseer returns an image URL. You do not push\npixels into Shopify Admin, and you do not publish the storefront.\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 store (fill in once):\n- Brand ID: bds_c_...\n- PDP hero, lifestyle still, and collection card aspectRatio: 1:1\n- Promo banner aspectRatio: 16:9\n- mode: design\n- resolution: 2K (use 1K if a file would miss Shopify's size cap)\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 theme pixel size.\n5. Generate one still. Return imageUrl, aspectRatio, mode, resolution,\n   useLogo, a one-line alt text suggestion (125 characters or fewer),\n   and a placement note: product media (name the product), collection\n   image (name the collection), or theme section on a duplicate theme.\n6. Do not tell the user the Shopify catalogue changed unless they confirm\n   they placed the file. Do not publish a theme, a product, or a collection.\n\nShopify placement is human only:\n- Files: Content > Files, Upload files. Public store files only.\n- Product media: Upload new, Select existing, or Select existing then\n  Add from URL. The first media item is the main image Shopify shows on\n  collection pages, cart, checkout, and the home page.\n- Collection image and theme Image fields: the person uploads a file.\n  Promo text belongs in the theme, not on the image, when the theme crops.\n- Do not call the Shopify Admin API. Do not invent API paths. Do not ask\n  for a Shopify token.\n\nOut of scope:\n- Slack replies, Buffer scheduling, and Zapier, Make, or n8n scenarios.\n- Webflow site placement, HubSpot files or ads, and Klaviyo email placement.\n- Prices, inventory, SKUs, and product descriptions.\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  pdp: \"1:1\",\n  hero: \"1:1\",\n  product: \"1:1\",\n  lifestyle: \"1:1\",\n  collection: \"1:1\",\n  card: \"1:1\",\n  square: \"1:1\",\n  \"1:1\": \"1:1\",\n  promo: \"16:9\",\n  banner: \"16:9\",\n  slideshow: \"16:9\",\n  tile: \"1:1\",\n  \"16:9\": \"16:9\",\n  landscape: \"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 PDP smoke test passes. They do not change Brandiseer's image contract, and they do not give Brandiseer a publish button.\n\n### Approval before the still is the main media\n\nAfter `imageUrl` is in the product **Media** section, a named reviewer checks the still and the alt text. Only then may someone drag it to the first position, where Shopify uses it on collection pages, the cart, the checkout, and the home page. Until that happens, keep the previous main image first. Brandiseer does not approve legal claims, prices, or offers.\n\nA theme promo stays on the duplicate until that same reviewer is happy. Publishing the theme is a separate admin action. This guide does not publish it.\n\n### One brand per Shopify store\n\nKeep a table: store name and `bds_c_...`. Require a store name on every brief when more than one store exists. If the name misses, stop and list the stores you configured. Confirm Brand IDs with `GET /api/v1/brands`. Never fall through to another client's Brand ID. There is no Shopify token in this table, because this guide does not call Shopify.\n\n### Credit soft-limit\n\nWhen `credits` is under a threshold you choose (for example 40), switch new product 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: store, product or collection or theme, slot, `brandId`, `mode`, `aspectRatio`, `resolution`, `imageUrl`, and whether it was uploaded, pasted with **Add from URL**, or left only in **Files**. Brandiseer does not write this log. Shopify does not send it back to Brandiseer.\n\n### Variant image (one frame, already on the product)\n\nShopify's variant article says you can assign one image to a variant, chosen from existing product images or uploaded from the device. Variants do not take 3D models or video. Add the lifestyle stills to the product gallery first, then assign one of those images to the variant. That assignment is a person in the **Variants** section. Read [Adding images to product variants](https://help.shopify.com/en/manual/products/product-media/add-images-variants) before you do it. Brandiseer does not map variants.\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- An email hero that lives in Klaviyo: [Klaviyo email heroes](/use-cases/klaviyo-email-heroes).\n\nDo not embed Buffer, a Slack desk, an always-on scenario, Webflow, HubSpot, or Klaviyo inside this Shopify guide.\n\n### Optional motion (not the product MVP)\n\nShopify product video is a different upload from a still. The product media types page lists video length up to 10 minutes, size up to 1 GB, resolution up to 4K (4096 x 2160 px), and file types `.mp4`, `.mov`, or `.webm`. YouTube or Vimeo links are the other option on that page. A theme must support video. This guide does not generate that file and does not publish it.\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 publish the product from this guide."},{"id":"limits-and-faq","heading":"Limits & FAQ","markdown":"### Does Brandiseer update Shopify or publish the storefront?\n\nNo. Brandiseer returns `imageUrl`. A person uploads that file or pastes the URL into product media, sets a collection image, or adds it to a theme section on a duplicate theme. Saving a live product's main media, publishing a theme, and publishing a collection to a sales channel stay in Shopify, after a person reviews the still.\n\n### Is there a Brandiseer app inside Shopify?\n\nNo. There is no Brandiseer block in the theme editor in this guide. Do not look for a native \"send to Shopify\" button on the Brandiseer side.\n\n### What if Shopify rejects the image?\n\nCheck the page for the surface you are uploading to. The numbers are not identical across Shopify's help pages:\n\n- [Uploading and managing files](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads): images up to 20 MB and 25 megapixels. Formats JPEG, PNG, WEBP, HEIC, and GIF. Aspect ratio between 100:1 and 1:100. File names must not start with a period. Names that end in `pico`, `icon`, `thumb`, `testing`, `small`, `compact`, `medium`, `large`, or `grande` can be rewritten by Shopify's CDN.\n- [Product media types](https://help.shopify.com/en/manual/products/product-media/product-media-types): product and collection images up to 5000 x 5000 px, or 25 megapixels, and smaller than 20 MB. It names PNG as the best type for most product images, then JPEG, and also lists PSD, TIFF, BMP, GIF, SVG, HEIC, and WebP.\n- [Uploading images](https://help.shopify.com/en/manual/online-store/images/theme-images): says images uploaded to Shopify cannot exceed 20 megapixels or 20 megabytes. The same page also tells you to upload higher-resolution files up to 5000 x 5000 px or 25 megapixels for quality. If the theme editor rejects the file, reduce the pixel size. The page lists JPEG, progressive JPEG, PNG, GIF, HEIC, and WebP, and says PSD, TIFF, and BMP are accepted and converted to JPEG or PNG.\n\nPrefer `2K`, download the file, and confirm size before upload. If **Add from URL** fails, upload the file from your computer. A product can hold up to 250 media items.\n\n### Which Shopify actions are in this guide?\n\nOnly human steps confirmed on Shopify's public help pages:\n\n- **Content > Files**, **Upload files**, up to 20 files at a time, on [Uploading and managing files](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads).\n- Product **Media**: **Upload new**, drag and drop, **Select existing**, and **Select existing** then **Add from URL**, on [Adding product media](https://help.shopify.com/en/manual/products/product-media/add-media). Drag the chosen image to the first position only when it should be the main media.\n- Alt text: open the media, **Add alt text**, **Save alt text**, on [Adding alt text to media](https://help.shopify.com/en/manual/products/product-media/add-alt-text).\n- Collection image: **Add image** on create, from [Legacy manual collections](https://help.shopify.com/en/manual/products/collections/manual-shopify-collection), or hover and **Change image** from [Editing collection details and layout](https://help.shopify.com/en/manual/products/collections/collection-layout).\n- Theme image: duplicate the theme, **Edit theme** on the copy, **Select image > Add images**, **Save**, from [Uploading images](https://help.shopify.com/en/manual/online-store/images/theme-images) and [Duplicating themes](https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes).\n\nThis guide does not call Shopify's Admin API and does not list those paths. It does not publish the theme.\n\n### Can the agent use a Shopify token or Sidekick?\n\nNo. This workflow has no Shopify token. Shopify's collection layout page mentions Sidekick for sorting products in a collection. This guide does not use Sidekick to place images or to publish.\n\n### Where does the key live?\n\nOnly the Brandiseer key (`bds_...`) is in play. It lives in the agent host's secret store. Never in a product description, a theme setting, a Slack message, a prompt you commit, or a git repo. Rotate it if it leaks. Poll a Brandiseer job with the same key that submitted it.\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\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\nShopify's uploading-images article also says embedded colour profiles are removed when the image is displayed, and that browsers then assume sRGB. A shift after upload can be that removal. It is separate from an off-brand prompt.\n\n### Why does the crop look wrong on the storefront?\n\nBrandiseer aspect ratios are `1:1`, `16:9`, `9:16`, and `4:3`. Themes crop banners and collection grids. Generate the PDP and the collection image at `1:1`, and a wide promo at `16:9`, then set a focal point if the theme cuts the frame. Do not ask Brandiseer for a custom pixel size inside the prompt.\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 product 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 that image becomes the main media or the theme is published. Brandiseer does not review the claim.\n\n### Does uploading to Files publish the product?\n\nNo. **Content > Files** stores the file. Shopify's own caution is that those files are for public store use, so treat the file URL as public. Assignment to a product, a collection, or a theme section is a later human step."},{"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:** Shopify product visuals\n**Length:** 45 to 75 seconds\n\n**Story beats:**\n\n1. A person asks Cursor or Cowork for a PDP hero with a layout-only brief\n2. The agent calls Brandiseer (MCP or REST v2) and shows an on-brand still\n3. `imageUrl` is uploaded to a product's Media section, and the previous main image stays first\n4. Optional cut: the same kind of still is placed on a duplicate theme section, still unpublished\n5. A human reviews alt text and leaves publish for a later step\n\n**On screen:** the agent transcript with the prompt (no colour or mood words), one finished still, and the Shopify Media section. Blur the Brandiseer API key. Do not show a published theme, and do not show a fake video player in the guide."},{"id":"additional-1-example-flows","heading":"Example flows","markdown":"### Flow A: PDP hero, placed in product media\n\nThe brief: \"PDP hero for the spring kit. One product, centred, full item in frame. No words on the image. No logo.\"\n\nThe agent selects the default `brandId`, sets `aspectRatio` to `1:1`, `mode` to `design`, `resolution` to `2K`, and `useLogo` to false, and returns `imageUrl` plus alt text such as \"Spring kit, centred, full item in frame\". You open the URL, download it, and on the product click **Upload new** or **Add from URL**. You check it is not stuck in the first position unless you mean it to be the main media. You add alt text. You do not launch the product from this step.\n\n### Flow B: Lifestyle stills for the same product\n\nThe brief lists three frames: the kit on a table, the kit open, and the kit in a hand. Each one says what is physically in the frame and that there is no on-image text. The agent generates three `1:1` stills and labels them. You upload three files into **Media** and leave the existing main image first. Three Design 2K stills cost 18 credits if all succeed. Failures refund.\n\n### Flow C: Collection card, unpublished copy\n\nThe brief: \"Collection image for Summer kits. Three products in a row. No words on the image.\"\n\nYou duplicate the collection so the copy is not on a sales channel. The agent returns a `1:1` still. You use **Change image** on the copy, click **Save**, and do not add Online Store. Product thumbnails inside the collection stay on each product's main media.\n\n### Flow D: Promo banner on a duplicate theme\n\nThe brief: \"Homepage banner. Product on the left. Leave the right half empty. The theme heading will sit there. No words on the image.\"\n\nThe agent uses `16:9` and says the headline stays in the theme. You duplicate the theme, **Edit theme** on the copy, **Select image > Add images**, then **Save**. You do not publish the theme. If the theme crops the banner, set a focal point on the product rather than baking type into the file.\n\n### Flow E: Credit check before a product 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`. Four Design 2K stills need 24 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 F: Style-only brief\n\nThe brief: \"Make the PDP feel premium and moody.\"\n\nThe agent does not generate. It asks which product, 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."},{"id":"additional-2-related-use-cases","heading":"Related use cases","markdown":"- [Klaviyo email heroes](/use-cases/klaviyo-email-heroes): on-brand email heroes placed in Klaviyo by a person\n- [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| Shopify | https://www.shopify.com |\n| Shopify files | https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads |\n| Shopify product media | https://help.shopify.com/en/manual/products/product-media/add-media |\n| Shopify product media types | https://help.shopify.com/en/manual/products/product-media/product-media-types |\n| Shopify alt text | https://help.shopify.com/en/manual/products/product-media/add-alt-text |\n| Shopify variant images | https://help.shopify.com/en/manual/products/product-media/add-images-variants |\n| Shopify manual collections | https://help.shopify.com/en/manual/products/collections/manual-shopify-collection |\n| Shopify collection layout | https://help.shopify.com/en/manual/products/collections/collection-layout |\n| Shopify theme images | https://help.shopify.com/en/manual/online-store/images/theme-images |\n| Shopify duplicate themes | https://help.shopify.com/en/manual/online-store/themes/managing-themes/duplicating-themes |\n| Visual pack manifest | `assets/MANIFEST.md` |\n| Sibling: Klaviyo email heroes | https://blog.brandiseer.com/use-cases/klaviyo-email-heroes |\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 Shopify product visuals. Brandiseer MCP and REST v2 image generation from Cursor or Claude Cowork, then a person places `imageUrl` in Shopify Files, product media, a collection image, or a theme section. Aligned with [guide/docs](https://brandiseer.com/guide/docs) and [guide/image](https://brandiseer.com/guide/image) (23 September 2026). Shopify placement steps follow the public help pages linked above. Brandiseer does not push into Shopify Admin and does not publish the storefront. Distinct from Slack creative desk, Buffer social scheduling, Zapier, Make, or n8n always-on HTTP, Webflow site visuals, HubSpot campaign creatives, and Klaviyo email heroes."},{"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 Shopify.\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 Shopify. 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 Shopify at the Brandiseer MCP URL.\n\n### Field mapping\n\n| Incoming field | API | Rule |\n| --- | --- | --- |\n| Slot (PDP hero, lifestyle, collection card, promo) | `aspectRatio` | PDP, lifestyle, collection card: `1:1`. Promo banner: `16:9`. Named landscape 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 theme text setting 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 product 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`. Drop to `1K` if the file would miss the Shopify cap for that surface. |\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\": \"Square PDP hero. Single product centred, standing upright, full item in frame. Plain surrounding space. No on-image text.\",\n  \"aspectRatio\": \"1:1\",\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. Shopify gets `imageUrl` (or a file you downloaded from it), uploaded or pasted by a person.\n\nSlot prompts that stay layout-only:\n\n| Slot | aspectRatio | Prompt |\n| --- | --- | --- |\n| PDP hero | `1:1` | Square PDP hero. Single product centred, standing upright, full item in frame. Plain surrounding space. No on-image text. |\n| Lifestyle still | `1:1` | Square lifestyle frame. The same product on a table, one prop beside it. Product fully visible. No on-image text. |\n| Collection card | `1:1` | Square collection image. Three products in a row, equal spacing, all fully visible. No on-image text. |\n| Promo banner | `16:9` | Wide storefront banner. Product centred on the left third. Empty right half for a heading the theme will set. No on-image text. |"}],"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/shopify-product-visuals","markdown":"https://blog.brandiseer.com/use-cases/shopify-product-visuals/agent.md","json":"https://blog.brandiseer.com/use-cases/shopify-product-visuals/guide.json"}}