@sogni-ai/sogni-creative-agent-skill/references/image-prompting.md

Sogni Creative Agent Skill: agent skill and CLI for Sogni AI image, 3D, speech, video, and music generation.

# Image Prompt Authoring Guide

Read this before writing any image prompt, whether you render it or return it
as text, and run `sogni-agent prompt-guide <model> --mode <generate|edit>` for
the model you chose (free and offline): the families below do not share one
prompt shape. Direct CLI mode
runs no model-aware prompt shaper and has no negative-prompt input, so when you
render, the positive prompt you write is all the model reads; state exclusions
positively in it.

When the creator asks for prompt text as the deliverable, a prompt-only request
does not authorize a render. Require both the exact target model/version and
the operation (`generate` or `edit`). If either is missing, ask for it. If the
exact pair is not registered, report that limitation;
never substitute another destination model's prompt contract.

## GPT Image 2.6 GIFs and annotations

Select `gpt-image-2.6-sunburst` or `gpt-image-2.6-flare` explicitly. For a GIF,
describe the action and return to the starting pose, then use `--output-format gif`,
`--image-frame-count 9`, and `--image-frame-duration-ms 200`. Nine frames at 200 ms
give a 1.8-second animation. Add original still images with `-c` to animate a
reference character, photo or artwork. GIFs exclude masks, markup, transparent
background and compression settings. Frames must be 2–16; each edge
is a multiple of 16, and width × height × frames must not exceed 8,294,400.

```bash
sogni-agent -m gpt-image-2.6-flare --output-format gif --width 320 --height 320 --image-quality medium --image-complexity high --image-frame-count 9 --image-frame-duration-ms 200 "A monkey lifts a lantern, blinks, and lowers it to its exact starting pose. Locked camera, seamless loop."
```

`--image-complexity low|medium|high` controls planning separately from rendering
quality. For annotation-guided still edits, use `--image-markup-url` with a
separate transparent PNG matching the first `--context` image after orientation.
Describe the requested edit in the prompt. Do not combine an annotation with a mask.
Use a concrete size and quality when comparing prices. GIF quotes reserve an output
budget and settle downward to confirmed provider usage when lower. Limits checked
November 7, 2026 PT; the live API enforces 16 frames despite the guide's higher limit.

## Output contracts by family

| Target family | Native prompt shape | Output envelope |
| --- | --- | --- |
| SD 1.5 | Weighted or comma-separated tags; quality/medium, subject, environment, lighting/camera | `positive_prompt:` plus `negative_prompt:` |
| SDXL | Hybrid natural language plus selective comma-separated style/quality terms; Pony variants start with their score tags | `positive_prompt:` plus `negative_prompt:` |
| FLUX.1 Schnell | One concise natural-language visual description centered on the subject, composition, light, and style; no SD score/tag soup | Prompt text only |
| FLUX 3 Image Klein | A full scene caption in plain sentences: subject, framing, setting, lighting, and style; name reference contributions by attachment order (the first image, the second image); no negative prompt (guidance is fixed at 1) | Prompt text only |
| Chroma 1 / v.46 / Detail | One coherent natural-language visual description; exact visible text in quotes; no SD score/tag soup | Prompt text only |
| Krea 2 / Krea 2 Turbo | Dense, fluent rich caption emphasizing observable composition, palette, light, texture, and atmosphere; no SD weighting syntax | Prompt text only |
| MOSS-Image SFT | Detailed natural-language caption, tags, or a supplied experimental JSON layout; preserve exact visible text and line breaks | Prompt text only; generation only |
| Qwen Image 2512 | Detailed natural-language description with explicit spatial relationships and exact quoted typography | `positive_prompt:` plus `negative_prompt:` |
| Z-Image | Compact instruction-aware natural-language caption | Foundation model: positive plus negative; Turbo: prompt text only |
| GPT Image 2 | Direct natural-language creative direction with explicit layout, hierarchy, and exact quoted copy | Prompt text only |
| Qwen / Krea / GPT edits | A direct delta instruction: what changes, what remains fixed, and the ordered role of each reference | Prompt text only |

The two-field envelope is exact: return two non-empty single lines in this
order and nothing else:

```text
positive_prompt: <model-ready positive prompt>
negative_prompt: <model-native exclusions and relevant failure modes>
```

Prompt-only families return the directly runnable prompt with no label,
Markdown fence, preamble, explanation, or render offer.

<!-- BEGIN GENERATED PROMPT GUIDE: image-models -->
<!-- Generated by npm run sync:prompt-guides from @sogni-ai/sogni-intelligence-client 4.26.0; edit the rules there, not here. -->

## Per-model rules from Sogni's image prompt writer

Before writing an image prompt, print the rules Sogni's own image prompt writer uses for that model and operation (free and offline). They hold the per-family detail behind the table above. An edit-only or generation-only selector has only that operation; pass the `-m` value you will render with.

| Family | Operation | Guide | Command |
| --- | --- | --- | --- |
| `chroma` | generate | Chroma text-to-image | `sogni-agent prompt-guide chroma1-hd --mode generate` |
| `flux1-schnell` | generate | FLUX.1 Schnell text-to-image | `sogni-agent prompt-guide flux1-schnell --mode generate` |
| `sdxl` | generate | Stable Diffusion XL text-to-image | `sogni-agent prompt-guide sdxl --mode generate` |
| `sd15` | generate | Stable Diffusion 1.5 text-to-image | `sogni-agent prompt-guide sd15 --mode generate` |
| `pony` | generate | Pony Diffusion XL text-to-image | `sogni-agent prompt-guide pony --mode generate` |
| `fast` | generate | Fast distilled Stable Diffusion text-to-image | `sogni-agent prompt-guide sdxl-turbo --mode generate` |
| `sd3` | generate | Stable Diffusion 3 text-to-image | `sogni-agent prompt-guide sd3 --mode generate` |
| `krea2` | generate | Krea 2 text-to-image | `sogni-agent prompt-guide krea-2 --mode generate` |
| `krea2` | edit | Krea 2 Identity Edit image editing | `sogni-agent prompt-guide krea2-identity-edit --mode edit` |
| `moss-image` | generate | MOSS-Image text-to-image | `sogni-agent prompt-guide moss-image --mode generate` |
| `flux3-klein` | generate | FLUX 3 Image Klein text-to-image | `sogni-agent prompt-guide flux-3-klein --mode generate` |
| `flux3-klein` | edit | FLUX 3 Image Klein image editing | `sogni-agent prompt-guide flux-3-klein --mode edit` |
| `qwen` | generate | Qwen Image 2512 text-to-image | `sogni-agent prompt-guide qwen-image-2512 --mode generate` |
| `qwen` | edit | Qwen Image Edit 2511 image editing | `sogni-agent prompt-guide qwen --mode edit` |
| `z-image` | generate | Z-Image text-to-image | `sogni-agent prompt-guide z-image --mode generate` |
| `gpt-image` | generate | GPT Image 2 text-to-image | `sogni-agent prompt-guide gpt-image-2 --mode generate` |
| `gpt-image` | edit | GPT Image 2 image editing | `sogni-agent prompt-guide gpt-image-2 --mode edit` |
| `seedream` | generate | Seedream 5.0 Pro Uncensored text-to-image | `sogni-agent prompt-guide seedream-5-pro-uncensored --mode generate` |
| `seedream` | edit | Seedream 5.0 Pro Uncensored image editing | `sogni-agent prompt-guide seedream-5-pro-uncensored --mode edit` |

<!-- END GENERATED PROMPT GUIDE: image-models -->

## Selector and operation discipline

- MOSS-Image SFT uses hosted selector `moss-image` and direct CLI model ID
  `moss_image_sft_int8_convrot`. The 8-step preset uses hosted selector
  `moss-image-8step` or direct ID `moss_image_sft_dmd8_int8_convrot`, with exactly
  8 steps and guidance 1. Both accept compatible Personal LoRAs. MOSS generates
  from text and has no uploaded-photo
  editing or reference-image input. JSON layouts use centered absolute pixel
  boxes in `[y_min,x_min,y_max,x_max]` order, `bbox_format: "yxyx"`, and
  `bbox_coord_space: "abs_centralized"`; match the generation canvas to the layout.

- Treat a model selector as an exact capability declaration, not a name to
  fuzzy-match into a convenient family. Every selector exposed by
  `generate_image` and `edit_image` must resolve in the shared registry.
- A family can have different operation profiles. `gpt-image-2` supports
  registered generation and edit contracts. A generation-only selector such
  as `flux1-schnell-fp8` or `krea-2-turbo` must not silently accept an edit
  request.
- `flux-3-klein` (FLUX 3 Image Klein) is one selector for both operations:
  generation with no references, a start image, or edits guided by up to ten
  references.
- `qwen` / `qwen-lightning` are edit selectors (Qwen Image Edit, an older
  model: only when the user names it) and `qwen-2512` / `qwen-2512-lightning`
  are generation selectors.
- Use `krea-identity-edit` or
  `dark-beast-krea2-identity-edit` for Krea identity edits. Assign
  `context_image_0` as the base and `context_image_1` as the secondary
  identity/outfit/pose/style reference when two inputs are requested.
- Preserve the creator's subjects, actions, spatial relationships, exact
  visible copy, proper nouns, style, and constraints. Add supporting visual
  detail without inventing extra objects, labels, slogans, characters, or
  story events.
- For a referenced person or character, distinguish a bounded edit from a
  creative transformation. Keep genuinely untargeted content stable for a
  bounded edit; express the recognizable individual in the requested medium
  for a transformation, including its implied retouching or physical redesign.
  Honor explicit locks without imposing a fixed face, texture, accessory,
  pose, framing or facial-exposure inventory. Source observations are evidence
  to interpret, not immutable requirements. Write task-specific art direction
  rather than appending a universal identity or beauty paragraph.
- Model capability selection comes from typed model and operation metadata.
  Never infer it from sentence-shape regexes or a list of creative keywords.

Primary references: [FLUX prompting](https://docs.bfl.ai/guides/prompting_unified_basics),
[Krea 2 technical report](https://www.krea.ai/blog/krea-2-technical-report),
[Qwen Image 2512](https://huggingface.co/Qwen/Qwen-Image-2512),
[Qwen Image Edit 2511](https://huggingface.co/Qwen/Qwen-Image-Edit-2511),
[Z-Image Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo), and
[Stability API](https://platform.stability.ai/docs/api-reference).