Media

Marketing visuals ride four lanes, and every one of them reads the same brand kit (content/media/brand-kit.json) — palette, type roles, the mark, the regional reality, the negative list — so a brand change lands everywhere at once instead of in whoever's memory.

Text-free photography — hero shots, product shots, lifestyle scenes, reels — is generated through Google direct (Nano Banana and Veo called at the source), through Higgsfield AI, or, for stills, through a ChatGPT seat — a human renderer driving GPT Image 2 from a prompt kun compiled. The first two reach the same models: Higgsfield's nano_banana_pro job type is Google's gemini-3-pro-image with a reseller's margin on it, so the /higgs skill treats the choice as purely commercial and walks a renderer ladder before spending. Either way the skill is one zero-question playbook — it picks model, aspect ratio, and style from pre-made tables, prices the job before spending, and downloads the result. Anything that carries copy — og images, infographics, testimonials, comparisons — renders deterministically from HTML templates on the carousel engine: Thmanyah type, the brand frame, exact platform sizes, and a 1-slide deck is a single-image asset. Finished media feeds the Social Hub, which stages the post for human approval before any channel sees it; everything generated or kept as reference is browsable in the showroom.

Editing real footage (cuts, Arabic captions, reels, title cards) is the edit lane: local and free. This page generates new media.

Production environment

Claude Code on the M4 is databayt's studio. The rule is free and local first: no paid generation API (decided 2026-10-07). Pick the tool by the job:

One pipeline behind all of it. media.sh (edit skill) encodes every deliverable the same way: tv-range BT.709, faststart, loudness normalised. It derives web images, checks everything with qa-pack against the budgets in engine.json → media, and publishes to cdn.databayt.org with hashed immutable URLs plus a manifest. Everything lives locally in ~/media/<repo>/<flow>/, and the CDN path mirrors the app's routes (hogwarts/students/add-student-ar.<hash>.mp4); the shoot docs hold the full grammar. The products render those through <TutorialVideo> (AV1 first, H.264 fallback, poster, captions) and <Shot> (AVIF/WebP <picture>). Media never enters git: the media-guard hook blocks it.

The gate. Before publishing, the media-qa agent reads the qa-pack output and judges what only eyes can: Arabic shaping, RTL, captions over the action, the brand's name and mark, private data, safe areas. It writes PASS / FIX / FAIL, and only a PASS ships.

Voice. Narration is synthesized locally (Chatterbox Multilingual v3) in one consented house voice. A team member records 10–15 s once (media.sh voice record house-ar --speaker "<name>"), then voice consent house-ar --given. The sample and the consent stay outside git and Drive. Every line is checked against a whisper transcript. With no valid consent, videos ship with captions only, and voice revoke lists every asset that then needs re-rendering.

Connectors (all on free tiers):

• Canva plugin (on): resize, brand check.
• Adobe for creativity: enable it per media session with claude plugin enable adobe-for-creativity@claude-plugins-official. Its 15 skills crowd the skill listing if always on.
• Claude Design: run /design-login once.
• Figma Weave: 150 credits a month. The figma-quota hook warns before the Figma MCP's ~20 calls a month run out.

The doctrine

The Google lane

The default renderer. scripts/gemini-media.mjs calls Google's own endpoints, so there is no credit ceiling to run into and no reseller margin to pay — a job costs what Google charges, per image or per second. Prices verified 2026-08-05 against ai.google.dev; the script's models subcommand prints the live table, which is what you should read after Google ships anything.

Two API shapes sit behind that one CLI. Images and Omni video go to the Interactions API (POST /v1beta/interactions) and come back synchronously with base64 bytes in steps[].content[]. Veo goes to :predictLongRunning, returns an operation name, and gets polled until done — the script downloads the mp4 immediately because Google deletes the render after two days. Every output carries an invisible SynthID watermark.

Copynode scripts/gemini-media.mjs cost --kind image --model pro --size 4K --count 3   # free
node scripts/gemini-media.mjs image --prompt "..." --ratio 4:5                    # prints estimate, exits
node scripts/gemini-media.mjs image --prompt "..." --ratio 4:5 --yes              # spends
node scripts/gemini-media.mjs video --prompt "..." --ratio 9:16 --seconds 8 --yes # $0.40, native audio
node scripts/higgs-library.mjs add ~/Downloads/gemini/<f> --source gemini --type hero --brand databayt

Spending is gated the way the Higgsfield lane gates it: a generate without --yes prints the estimate and exits. Setup is one line in kun's central .env — GEMINI_API_KEY= from AI Studio — and the script trims the value on read, because a trailing newline pasted out of a dashboard turns the auth header into an opaque 400.

There is no free tier for images — settled by running it (2026-08-05). The key authenticates, sees all 58 models, and generates text fine on the free tier. Image generation returns 429 … generate_content_free_tier_requests, limit: 0 — a quota that was never above zero, not one we used up. Google's pricing page was right; the third-party "~500 images/day" reports are wrong. The lane renders nothing until billing is enabled on project gen-lang-client-0243019665, which AI Studio will pair with a monthly spend cap — the safe way to switch it on.

Higgsfield model defaults

Costs are per job, re-verified 2026-07-27 with higgsfield generate cost.

Naming trap: nano_banana_flash is Nano Banana 2; nano_banana_pro is Nano Banana Pro. There is no nano_banana_2 job type — that ID was retired and now errors. Only the seedance family accepts --video-references.

Higgsfield workflow

Copyhiggsfield account status                            # preflight — re-auth only if this fails
node scripts/higgs-library.mjs lookup \
  --prompt "..." --model z_image --ratio 16:9        # free — already own it?
higgsfield generate cost z_image --prompt "..."      # free estimate
higgsfield generate create z_image --prompt "..." --aspect_ratio 16:9 --wait --json
higgsfield generate create kling3_0_turbo --prompt "..." --start-image <winner> --wait --json

generate has exactly six subcommands — cost, create, get, list, wait, workflow. Every job goes through create; there is no generate image or generate video.

Results are JSON arrays carrying result_url; outputs land in ~/Downloads/higgs/ as YYYY-MM-DD-<slug>.<ext>.

The ChatGPT seat lane

Owner: Sedon, on a $20 ChatGPT Plus seat. Roughly 50 images per rolling 3-hour window — call it 200 a day — at an effective cost under a cent each, which at a Higgsfield balance of 0.7 credits is the only image capacity the company currently has.

The constraint that shapes the whole lane: a ChatGPT plan is not API access. GPT-5.6 Sol is a reasoning model with text output; it renders pictures by calling the image tool, which is GPT Image 2. Both live behind the chat UI on a seat, and the API is separately billed with its own key. So no kun server can call this lane. kun compiles the prompt, a human renders, kun ingests the file — the seat is a renderer, not an endpoint.

What makes the output consistent is a ChatGPT Project, not a good prompt. The project carries the standing brand instructions and the mark as an attached file; every chat inside it inherits both, so the tenth render matches the first.

Copynode scripts/media-brief.mjs project                   # paste once into the Project's instructions
node scripts/media-brief.mjs types                     # what each type is, and which lane owns it
node scripts/media-brief.mjs brief --type hero \
  --subject "An empty classroom in early morning light"  # paste per asset

The queue

The scripts above are the desk version. The lane's real surface is the Media stage, because the renderer is a person holding a phone, and the ChatGPT app is on that phone. Briefs waiting appear at the top of the page: Copy prompt puts the compiled text on the clipboard, Upload render takes the image back. The image is re-encoded to WebP in the browser first — a 1792×1024 PNG off GPT Image 2 runs 2–4MB, more than a Server Action accepts and far more than a social image needs; the canvas hop lands it near 300KB. It uploads to the same bucket and media/<brand>/ layout the library uses, then appears in the grid below, attachable to the Publish tray like any other asset.

Where the work comes from is the point. The Monday tick (social-drafts.mjs seed --auto) already files the week's copy asks from content/social/pillars.json; it now files a media brief from the same pillar whenever that pillar carries a visual. The week's picture and the week's words come from one source, so nobody invents a scene — and a pillar whose image belongs to the template lane carries visual: null and files nothing, because filling a human's queue with work that renders better as HTML is worse than filing nothing.

The prompt is frozen into the row at file time, never recompiled. The kit will change; what a given image was actually asked for must not change under it.

brief refuses any type whose lane is not chatgpt — asking a raster model for an og image is exactly the mistake the no-text doctrine exists to prevent, so it fails loudly instead of compiling a prompt that would produce broken Arabic. Six types compile: hero, lifestyle, product, mockup, story, and plate (a text-free background the template lane sets copy over). Sizes are pre-checked against GPT Image 2's rule — both sides divisible by 16, ratio within 1:3 to 3:1 — so they are pasted, never rounded.

Renders come back through the same library as everything else, tagged with their renderer:

Copynode scripts/higgs-library.mjs add ~/Downloads/higgs/<file> \
  --brand hogwarts --type hero --source chatgpt --model gpt-image-2
node scripts/higgs-library.mjs push

--source is what keeps the showroom honest — without it a ChatGPT render inherits a Higgsfield badge and a credit cost it never spent.

Asset library

Every paid job is fingerprinted by (prompt, model, ratio, resolution) in content/media/library.json and mirrored to object storage, so the same shot is never bought twice and assets survive a cleared Downloads folder.

Copynode scripts/higgs-library.mjs lookup --prompt "..." --model M --ratio 16:9
node scripts/higgs-library.mjs add <file> --prompt "..." --model M --brand hogwarts --credits 1
node scripts/higgs-library.mjs import    # register whatever is already on disk
node scripts/higgs-library.mjs push      # mirror to the serving origin
node scripts/higgs-library.mjs stats     # assets, credits spent, credits saved

Prompts are normalized before hashing, so trivial rewording still hits; a different ratio or model is correctly a miss. /social --media consults the library before spending a credit.

Setup

Google lane — GEMINI_API_KEY in the central .env, already wired from the AI Studio key named kun. Nothing to install; the script uses fetch. Note current keys use Google's new format (AQ.Ab…, 53 chars), not the legacy AIza… — anything validating on the old prefix will reject a valid key. Rendering additionally needs billing enabled on the project; the key alone is not enough.

Higgsfield lane

1. Install the higgsfield CLI (aliases higgs, hf).
2. higgsfield auth login — browser OAuth, completes hands-free.
3. higgsfield workspace set <workspace-id> — required after every re-auth.
4. Brand kit and web product IDs are pinned in the skill so output stays on-brand.

Credentials live in the Keychain, never in a repo — see Credentials.

Known limits

• The Higgsfield balance is 0.7 credits (2026-07-27). Only z_image drafts still run; every final image, hero, and video is unaffordable there until the workspace is topped up. Free-plan credits look like a one-time grant, not a monthly refill. This is what demoted the lane from default to alternate.
• The Google lane is blocked on billing, not on a missing key — see the callout above, settled 2026-08-05 and re-confirmed 2026-08-19. The key exists, is in the central .env and in Vercel production, and lists all six image models. Enabling billing on project gen-lang-client-0243019665 is the single remaining step, and it is new external API spend, which the subscription-only posture says is Abdout's call, not a session's. Re-confirming costs nothing — the spend gate refuses before it generates, so image --model lite --yes is a free liveness probe.
• The Plus trial requires a working card — currently blocked by the Mada rejection.
• The Higgsfield MCP endpoint is registered but unauthenticated; the CLI is the primary lane.
• Video is entirely untested — no clip has ever been generated on any lane. Veo Lite at $0.40 per 8-second clip is the cheapest way to change that.
• The Media Studio does not render. It compiles a prompt and offers a curated still from public/media when one fits; the badge names the file, not a model. Both raster lanes are CLI- or seat-driven and unreachable from a Server Action. A studio badge that names a model would be the --source fault above, applied to the generator instead of the library.
• S3 is configured in production as of 2026-08-19. AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION were absent from the Vercel project, so isStorageConfigured() returned false there and putMedia() silently no-opped — every render uploaded through the Brief Queue was accepted and then dropped, in production only. Added and redeployed; verified with a write/read/delete round-trip against media/unsorted/ (IAM user hogwarts, origin readback 200).
• cdn.databayt.org serves published keys (200, immutable); a key that was never uploaded answers 403, not 404 (private OAC origin), so a 403 means "not published", not an outage.
• Arabic creative still needs manual typography in post. Nano Banana Pro claims accurate multilingual text rendering, which would overturn that rule if it holds for Arabic script shaping — one $0.134 render against the same string set in Thmanyah settles it. Untested, so the no-text-in-rasters rule stands.

The showroom

The Media stage of the Hub is a gallery of both registries — content/media/library.json (what we generated, S3-served) and content/media/references.json (what we keep as reference or inspiration) — filterable by collection, brand, and asset type. Rendered decks link to their live carousel routes.

Attach is the hand-off. A generated asset's card carries an Attach button that puts it in the Hub's attachment tray, which rides to the Publish stage and becomes the draft's media half — the tray survives the navigation, so browsing here and deciding there is one motion. Copy URL stays for the cases that need a URL in hand. A session does the same move from the CLI: node scripts/social-drafts.mjs attach <askId> --media "<cdnUrl>".

Pick before you generate. A cdnUrl already in the library is free and instant; the drafting queue's answering session matches by the brief's (library: <id>) hint or by brand + asset type, and only a genuine miss justifies spending credits.

content/media/30 generated · 42 references

mkan/mkan-logo-c1

mkan/mkan-logo-c2

mkan/mkan-logo-c3

mkan/mkan-logo-c4

mkan/mkan-logo-final

/smoke-test

mkan/mkan-belo-pro

mkan/mkan-belo-v1

Rendered from library.json + references.json — the same registries as the full showroom at /social/media.

Asset vocabulary

The canonical asset types (src/components/root/social/showroom/taxonomy.ts). The lane column is the doctrine as data: AI typography breaks (Arabic doubly so), so any type that carries copy renders on the template lane and only text-free photography spends Higgsfield credits. Industry names are the terms designers and the Meta Ad Library speak.

Register the type at generation time — node scripts/higgs-library.mjs add <file> --type hero … — and the showroom files it; untyped legacy rows read as Unsorted.

Composition & style

Compositional frameworks and treatments are modifiers, not asset types — they shape the prompt (higgs lane) or the slide layout (template lane). The two brand style blocks already encode the house defaults:

Typography in creatives

Typographic hierarchy, text lockups, and font pairing are the template lane's whole craft — and the reason it exists. The house pairing is fixed: Thmanyah Serif Display Black + ss01 for Arabic headlines (the signature calligraphic look), Thmanyah Sans for Arabic body, Geist for English — encoded once in carousel/slides.tsx and inherited by every template. Arabic never takes letter-spacing (it breaks the connected script). The hard rule stands: no text inside AI-generated visuals; a testimonial lockup or copy-centric graphic is HTML, rendered — the license-safe fetch script provisions the fonts, and the woff2 files never land in git or on the CDN.

Where to look

A find worth keeping becomes a card in content/media/references.json — source link + "what to steal"; an optional thumb goes under public/social/media/refs/.

Competitor teardown — school systems

What the SMS category's creatives actually look like, per segment:

The open-source pitch (OpenEduCat's lane) overlaps ours; the typographic-trust lane (Gradelink's) is where the Thmanyah template system outclasses the category.

The four ad pillars

The category's proven layouts, mapped to our lanes — say the pillar's type in a session and the right lane runs:

The demo deck hogwarts/sms-pillars renders all four template-lane pillars; at 0.7 credits, the higgs pillar is plan-first (draft on z_image at 0.15 only when the library has no hit).

Production Scenarios & Playbooks

The Media Studio and Pipeline serve concrete production scenarios for every databayt product. Rather than prompting from scratch, choose a playbook below:

Scenario 1: Mkan Port Sudan Property Tour & Listing Pack

• Objective: Complete marketing pack for a coastal rental in Port Sudan (Hayy Al-Shati or Salbona).
• Brand: Mkan (mkan.sd) — see Mkan Social Strategy & Twenty CRM Schema.
• Workflow:
  1. Open Media Studio with Mkan selected.
  2. Select Walkthrough (9:16 · Video) — compiles the 35mm handheld coastal-drift prompt (interior to Red Sea balcony, 24fps, coastal wind & tea foley). It does not render; take the prompt to scripts/video-media.mjs or the Veo lane below.
  3. Select Post (4:5 · Image) — compiles 50mm architectural framing with morning sunlight and clay accent (#e05638), and offers the closest curated still from the library as a starting point. The badge says which; no model runs on this surface.
  4. Select Infographic (1:1 · Template) — renders live preview of property amenities (24/7 Standby Power, Split AC, Red Sea shore distance).
  5. Click Draft Copy with this Media — hands off to Draft Agent (/social/draft) for bilingual Arabic/English copy.

Scenario 2: Hogwarts Academic Admission Campaign Pack

• Objective: Multi-format promotional creative for school enrollment drives and SIS migration.
• Brand: Hogwarts (ed.databayt.org) — see Hogwarts Social Playbook & Carousel Engine.
• Workflow:
  1. Open Media Studio with Hogwarts selected.
  2. Select Ad (16:9 · Image) — compiles hero promotional banner with generous negative space for zero-paperwork headlines.
  3. Select Carousel (4:5 · Template) — generates 5-slide deck directives ("5 reasons schools switch from spreadsheets to Hogwarts").
  4. Select Testimonial (1:1 · Template) — renders deterministic Thmanyah Serif Display quote card with Principal Dr. Tariq's quote.
  5. Click Draft Copy with this Media to compose the accompanying announcement.

Scenario 3: Airbnb Swipe File & Repurposing for Mkan

• Objective: Adapt proven multi-billion-dollar Airbnb advertising formulas into Mkan Port Sudan campaigns with zero prompt fatigue.
• Brand: Mkan (mkan.sd) — see Mkan Social.
• Workflow:
  1. In Showroom Gallery, browse the Airbnb Inspiration Shelf.
  2. Click Use in Studio on any reference card (Belong Anywhere / Strangers, Categories & Standout Stays, Host Recruitment).
  3. The prompt box, asset format, and aspect ratio auto-populate and compile tailored Mkan Port Sudan directives.

Scenario 4: Fast Deterministic Text-Bearing Cards

• Objective: Generate quote cards, infographic statistics, and multi-slide decks with authentic Arabic typography and zero AI text hallucinations.
• Brands: All brands (mkan, hogwarts, databayt, sijillee, moallimee) — see Carousel Documentation.
• Workflow:
  1. Select Infographic, Carousel, or Testimonial in Media Studio.
  2. The browser renders a live visual card preview using Thmanyah Serif Display and brand palette.
  3. Decks render deterministically via node scripts/render-carousel.mjs <deck-slug>.

Scenario 5: High-Impact Video Generation

• Objective: 24fps motion tours, cinematic dolly glides, and feature demos with native audio.
• Engines: Google Veo Lane (scripts/gemini-media.mjs) · Higgsfield CLI.
• Workflow:
  1. Toggle Video icon (🎥) on Media Studio.
  2. Select Walkthrough and compile the 5-beat camera motion and foley prompt.
  3. Run Google Veo Lite ($0.40 / 8s clip):

     Copynode scripts/gemini-media.mjs video --prompt "..." --ratio 9:16 --seconds 8 --yes

  4. Upload finished render to Brief Queue. Blocked today: the queue accepts image/webp|png|jpeg only, capped at 4MB (RENDER_TYPES in src/actions/post-social.ts), so every mp4 is rejected at the MIME check. Keep the clip in ~/Downloads and register it with higgs-library.mjs add until the queue learns video.

Scenario 6: Social Pipeline Hand-off & Cross-Platform Broadcast

• Objective: Bridge visual assets into multi-channel social posts across X, Facebook, LinkedIn, Instagram, and TikTok.
• Workflow:
  1. In Media Studio or Showroom, click Attach or Draft Copy with this Media.
  2. The attachment tray retains media URLs across stages.
  3. In Social Draft, generate bilingual copy matching the visual tone.
  4. In Social Publish, review preview across channels and approve immediately or schedule to the automated drain.

Related

• Social Automation — where generated media gets published
• Mkan Social Playbook — rentals marketing & Airbnb alignment
• Hogwarts Social Playbook — school SIS marketing
• Carousel — the template lane's engine: decks, archetypes, sizes
• CRM & Listings Schema — Twenty CRM listings integration
• Brand & Voice — the rules every visual obeys
• Credentials — where the Higgsfield session lives