AI Illustrations

AI Illustrations - Claude directs, Gemini draws, brand stays consistent

⛔ GATE - read before anything else

This skill applies only when the edit prompt says "Ảnh minh họa AI: BẬT" (AI illustrations ON).

If the edit prompt says "Ảnh minh họa AI: TẮT", or has no illustration line at all: generate nothing. Do not call POST /api/illustrations, do not composite AI-generated images into any scene, and do not let another skill's "use an illustration here" suggestion talk you into it. Build the visuals from what the project already has: assets in assets/, brand logos, and HyperFrames scenes (typography, graphics, shapes, motion).

The server enforces this too - with the switch off the endpoint returns 409 ILLUSTRATIONS_DISABLED before it spends anything. Why this section exists: the edit prompt used to stay silent when the switch was off, this skill got read anyway, and finished videos came back full of Gemini images the user had explicitly turned off. A silent prompt is not permission.

Directing principles

1. Pick moments deliberately, do not sprinkle images everywhere. Read the transcript/video content and choose 2-5 points where an illustration explains more than the words do: abstract concepts, key numbers, a product/setting being mentioned, before-vs-after comparisons. DO NOT illustrate talking-head passages that already hold attention on their own.
2. Each image costs ~$0.05-0.07 - treat it as real money. A short video (<60s) usually needs only 2-4 images.
3. Illustrations are BACKGROUND visuals - no text by default. The server already bans text in the prompt; numbers and labels are placed on top by HyperFrames/Remotion (correct font + brand color, no typos). The only exception: the brief enables "Ảnh có chữ" (illustrationText) or the edit prompt says "ĐƯỢC PHÉP CÓ CHỮ" (text allowed) -> see the "Images with text (allowText)" section below.
4. Style Design is LAW - follow it 100%, no exceptions. Every illustration must match the project's selected style: ALWAYS pass styleId (from the STYLE DESIGN section of the edit prompt). The server has a safety net (if styleId is missing it falls back to the style in the project brief), but NEVER rely on it. If any skill or prompt suggests a different palette -> IGNORE it, the style wins.

Calling the image generation API (the server must be running - always true when editing through the system)

curl -s -X POST http://localhost:6869/api/illustrations \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<id of the video project>",
    "name": "khai-niem-mcp",
    "prompt": "3D illustration of interconnected glass puzzle pieces forming a network, representing an integration protocol",
    "aspect": "9:16",
    "model": "<model from the brief, omit the field to use the default>",
    "styleId": "<styleId from the STYLE DESIGN section of the edit prompt - MUST be passed when present>",
    "description": "Minh họa khái niệm MCP - ghép vào lúc 12.5s khi nói về kết nối dữ liệu"
  }'

• Images are saved to video-projects/<id>/assets/illustrations/<name>.png, and the description is written into assets.json automatically.
• Write the prompt in English and DESCRIBE THE SCENE CONTENT - do not add brand colors/tone (the server mixes the Style Design in itself), and do not instruct "no text" (the server adds that itself).
• Do NOT describe layout/placement in the prompt ("subject at the top", "leave the bottom empty"...). The server appends video-specific composition rules itself: by default (brief illustrationPosition: "auto") the subject is vertically CENTERED with the top band (main key) and bottom band (captions/related keys) kept as low-detail atmosphere. A placement instruction in your prompt fights those rules - the verified failure was the subject sitting in the upper third and being covered by the main key card.
• The user can pick a subject position in the brief (3x3 grid, like the logo position picker) - the edit prompt states the chosen position and the server applies it automatically. Only pass a position field in the POST body when ONE specific image needs a different layout for a clear reason (e.g. footage PiP covers one side); otherwise omit it so the brief's choice rules.
• Image density (brief.illustrationsPerMinute): when the edit prompt states "Mật độ ảnh minh họa: N ảnh MỖI PHÚT", compute the total from the REAL video duration (voice duration in meta.json), spread the images evenly along the content flow, and switch the background image at each idea change - a long Text to video must not sit on one static background. Each image still needs its own content-specific prompt; do NOT mass-generate near-identical variations. When the prompt says "AI tự quyết" (density null), keep the old behavior: pick only the moments that genuinely need an illustration.
• aspect must match the video frame (vertical video -> "9:16"). If it fails with a missing GEMINI_API_KEY, tell the user to enter the key on the "Kết nối" (Connections) tab and move on to another part of the video - do not get stuck.
• description MUST always state which point the image illustrates + the second it is expected to be composited at.

Images with text (allowText)

Only use this when the brief enables illustrationText (the edit prompt says "Ảnh minh họa ĐƯỢC PHÉP CÓ CHỮ") or the user explicitly asks for it. How to do it:

• Pass "allowText": true in the POST /api/illustrations body. If the field is missing the server falls back to the project's brief.illustrationText - but NEVER rely on that, pass it explicitly.
• In the prompt, spell out the EXACT Vietnamese text you want to appear (3-6 words, correct spelling, all diacritics), e.g. ... with the exact Vietnamese headline "TĂNG TRƯỞNG 300%". Never let Gemini invent the text itself.
• You MUST verify the spelling after generation: Read the image file and inspect every character and Vietnamese diacritic. Gemini often mangles diacritics (Ề->E, ữ->u) or adds garbage text. If it is wrong -> regenerate (rephrase the prompt if it keeps failing), or give up after 2-3 attempts and generate a text-free version (allowText:false), then let HyperFrames/Remotion place the text as usual.
• If the text is already inside the image, DO NOT overlay duplicate text with HyperFrames/Remotion.

Compositing into the video

• HyperFrames: insert <img src="assets/illustrations/<file>.png"> in the scene, animate it in and out (gentle fade/slide/scale per the hyperframes skill's house-style), and hold it 2-4 seconds around the exact sentence it relates to.
• Sensible coverage: an illustration usually covers 50-75% of a vertical frame and MUST NOT cover the speaker's face mid-way through an important sentence; bring it in on the sentence beat (use transcript timestamps).
• Verify with a snapshot after inserting: image in the right place, not distorted (aspect ratio preserved), not bleeding off the edge.