AI-KSK/ideogram4-kj-prompt-crafter

Ideogram 4 KJ Prompt Crafter

Turn arbitrary input into one production-ready Ideogram 4 caption JSON object that follows the current Ideogram OSS schema and KJNodes assembly order.

Source target

Target the final caption consumed by Ideogram 4 Prompt Builder KJ, not the request envelope used by a hosted magic-prompt API. Never add aspect_ratio, width, or height to the caption. Width and height are separate KJ node inputs.

Use the schema snapshot in references/schema.md. When exact source provenance or version drift matters, read references/source-baseline.md.

Default output contract

• Return exactly one valid JSON object and nothing else unless the user explicitly asks for explanation, alternatives, or analysis.
• Do not wrap the JSON in Markdown fences.
• Do not add headings, labels, commentary, a negative prompt, usage instructions, or a separate paste block.
• Preserve literal non-ASCII text as UTF-8; do not replace it with \uXXXX escapes.
• Keep canonical key order.
• Prefer compact one-line JSON for final delivery. Use pretty JSON only when the user asks for readability.
• Do not expose reasoning or planning notes.

Workflow

1. Extract the brief

Silently identify:

• non-negotiable subjects, counts, actions, relationships, setting, mood, medium, viewpoint, colors, brands, and exclusions;
• every quoted string, title, label, numeral, date, price, logo word, or line of copy that must be visible;
• whether the input describes a captured scene, designed artifact, illustration, render, transparent cutout, or reconstruction of an attached image;
• scene-shell content versus independently placeable elements;
• explicit spatial instructions worth encoding as bounding boxes.

Preserve all explicit facts. Resolve harmless ambiguity with one concrete, coherent choice. Do not hedge with “or,” “maybe,” “such as,” or lists of alternatives.

2. Choose the caption shape

Always emit these top-level keys in this order when applicable:

1. high_level_description — strongly recommended; normally include it.
2. style_description — include when style or medium control adds value.
3. compositional_deconstruction — required.

Inside compositional_deconstruction, always emit background before elements.

3. Write the high-level description

Write one dense sentence, or at most two, summarizing the subject, medium, action, composition, and overall visual character. Start with the subject or artifact itself, not “This image shows.” Keep granular clothing, props, typography, and materials for elements.

For a transparent result, include the exact phrase on a transparent background here and set background to exactly transparent background.

4. Build style_description

Choose exactly one branch:

• Photo: aesthetics, lighting, photo, medium, optional color_palette.
• Non-photo: aesthetics, lighting, medium, art_style, optional color_palette.

Never include both photo and art_style. Use medium: "photograph" for photographic work. For posters, layouts, packaging, UI, logos, and editorial designs, prefer medium: "graphic_design" with art_style.

Describe style once, precisely. Avoid keyword soup, contradictory lenses, mutually exclusive media, and redundant quality slogans.

5. Separate background from elements

Use background for the scene shell and global environment: sky, atmosphere, horizon, distant scenery, walls, ceiling, ground/floor/road/water surface, ambient illumination, and diffuse distant crowds.

Use one obj element per coherent independently placeable subject or object. Keep anatomy and structural parts inside that object's desc; do not split a person into face, hands, clothes, and limbs. Use separate elements for distinct people, animals, products, furniture, signs, foreground props, badges, decorative devices, or speech-bubble containers.

Do not describe the same component in both background and an element. An architecturally fixed focal feature may be mentioned briefly in the shell and emitted first as “the primary background element” only when the dual anchor is genuinely needed.

6. Write detailed element descriptions

For every obj, describe identity first, then the visible attributes that distinguish it:

• people: apparent age range, skin tone, hair, visible garments and colors, expression, gaze, pose/action, held item, distinctive accessory;
• products/objects: category, silhouette, material, finish, color, construction, functional parts, label placement, orientation, condition;
• designed devices: shape, position, scale, fill, stroke, texture, hierarchy, relationship to nearby text;
• structures: type, material, color, openings, roof/façade form, significant fixed details.

Keep global lighting, camera effects, floor state, and atmospheric treatment out of object descriptions. Describe observable reality rather than praise words such as “stunning” or “beautiful.”

For dense uncountable content such as stars, crowds, mist, grass, or particles, describe the field in background or one collective element instead of fabricating hundreds of entries. Enumerate every individually named or sequentially identified item the user supplies.

Read references/craft.md for the complete handling rules for sparse briefs, realism, typography, branded work, reference images, and exclusions.

7. Handle visible text exactly

Create a text element for each visually distinct text block. Preserve the requested characters, capitalization, punctuation, spelling, and language verbatim in text. Encode line breaks inside one block as \n.

Describe typography and placement in desc: relative size, hierarchy, type category, weight, posture, color, alignment, orientation, spacing, treatment, and container relationship. Do not repeat the literal characters in desc.

Use English for descriptive prose unless the user explicitly requests another prompt language. Keep visible text in its original/requested language.

8. Use bounding boxes without requiring aspect ratio

Do not ask for or invent an aspect ratio. Omit bbox by default when the brief has no meaningful spatial constraint; KJ's visual editor can add boxes later.

Add bbox only when placement is explicit or composition-critical, such as a title at the top, two named subjects on opposite sides, a logo in a corner, a product label, or geometry observed in a reference image. Use normalized integer coordinates on a 0–1000 grid in this exact order:

[y_min, x_min, y_max, x_max]

Ensure 0 <= y_min < y_max <= 1000 and 0 <= x_min < x_max <= 1000. Use tight non-degenerate boxes, avoid one box unintentionally swallowing another subject, and allow intentional overlap only when elements physically overlap.

9. Use palettes deliberately

• Use uppercase full hex strings only: #RRGGBB.
• Allow at most 16 colors in style_description.color_palette.
• Allow at most 5 colors in each element palette.
• Include a palette only when it improves control. Choose colors that match the described materials and include both dominant and contrast colors where useful.

10. Run the final audit

Before responding, verify:

• valid JSON with no comments or trailing commas;
• only supported keys;
• canonical key order;
• exactly one style branch;
• required background and elements;
• every named subject and every required visible text block is represented;
• no aspect_ratio, width, height, negative_prompt, or invented extension keys;
• text is verbatim and non-ASCII remains literal;
• boxes use Ideogram's YX order and legal integers;
• palettes respect format and caps;
• no duplicated scene component, contradictory instruction, vague alternative, or accidental extra text.

When working with a saved caption, run:

python scripts/validate_caption.py caption.json

To canonicalize a structurally valid caption:

python scripts/validate_caption.py caption.json --canonicalize > caption.min.json

Input modes

• Tiny idea: enrich it with specific but coherent visual decisions; do not bury the requested subject under invented spectacle.
• Detailed brief: preserve every explicit constraint and convert the hierarchy into background, objects, and text.
• Existing prompt: repair it into the schema without silently dropping content.
• Attached image: describe only visible or safely inferable details; reproduce readable text exactly and approximate composition with boxes only when useful.
• Reference plus change request: preserve retained geometry/identity and encode only the requested changes.
• Non-English input: understand it directly; use English descriptive prose by default while preserving visible text verbatim.
• Exclusions: enforce them by omitting or positively specifying the desired alternative. The schema has no negative-prompt field.
• Multiple variants: produce separate valid JSON objects only when explicitly requested; do not place them inside an array intended for the KJ node.

For representative outputs, read references/examples.md.