1#### Imagine API
2
3# Image Prompting Guide
4
5This guide covers prompts for `grok-imagine-image-2.0` stills: a new image from text, or an edit of an existing one.
6
7The score that matters is whether the subject in the picture matches the subject in the prompt. Palette, film grain, and styling come after that.
8
9## Request settings
10
11Generate a new image with [`/v1/images/generations`](/developers/model-capabilities/images/generation):
12
13```bash
14curl -X POST https://api.x.ai/v1/images/generations \
15 -H "Authorization: Bearer $XAI_API_KEY" \
16 -H "Content-Type: application/json" \
17 -d '{
18 "model": "grok-imagine-image-2.0",
19 "prompt": "...",
20 "aspect_ratio": "3:2",
21 "resolution": "2k",
22 "quality": "medium",
23 "response_format": "b64_json",
24 "n": 1
25 }'
26```
27
28Use [`/v1/images/edits`](/developers/model-capabilities/images/editing) when a picture already has the right subject and layout:
29
30```bash
31curl -X POST https://api.x.ai/v1/images/edits \
32 -H "Authorization: Bearer $XAI_API_KEY" \
33 -H "Content-Type: application/json" \
34 -d '{
35 "model": "grok-imagine-image-2.0",
36 "prompt": "...",
37 "image": {"url": "data:image/jpeg;base64,...", "type": "image_url"},
38 "aspect_ratio": "3:2",
39 "resolution": "2k",
40 "quality": "medium",
41 "response_format": "b64_json"
42 }'
43```
44
45Lock `aspect_ratio` across a series so the images sit together; `3:2` suits most photographs. [`quality`](/developers/model-capabilities/images/generation#quality) accepts `low`, `medium`, or `auto`, and `auto` currently serves `low` on generation and `medium` on edit. Pin `medium` and `2k` when fine detail has to be recognizable. Generated URLs are temporary, so request `b64_json` when you plan to keep the file, or store it with [Imagine outputs](/developers/model-capabilities/imagine/files/outputs).
46
47## Write the subject first
48
49Open with one sentence that names the subject, the state or form it is in, what holds or supports it, and the setting.
50
51> A matte sage-green ceramic pour-over dripper sitting on a glass carafe half full of coffee, on a pale oak counter against white square tile.
52
53Then describe the subject as something you could point at and recognize:
54
55* Every key element, by name, in the form it takes in the picture. A wool coat is heavy twill with a visible weave. Coffee in a glass carafe is dark amber, lighter at the edges. A paperback has a creased spine. Feta in a salad is irregular crumbles.
56* How many. Two mugs. One open notebook. One person, seen from the waist up. One wedge pulled a finger-width aside.
57* Where the eye enters. A 45-degree three-quarter view at counter height, or a straight-down overhead of the desk. State it once in the subject paragraph, and repeat it in the composition paragraph in the same words.
58
59A prompt that leads with mood, film stock, or a list of things to avoid produces a styled scene whose subject is a stand-in.
60
61## Shape of a prompt
62
63Keep the same order in every prompt of a series:
64
651. **Subject.** What it is, its form, what holds or supports it, the setting.
662. **Details and focal point.** Key elements, materials, count, and the camera angle, written as one cluster that fills the frame.
673. **Art direction.** The color fields and the two or three props, each named: oak counter, white tile, linen towel, one brass spoon.
684. **Light.** The source, its direction, and how hard it is, for example hard afternoon sun from the left with on-camera fill flash. Say what the highlights and shadows look like, and ask for an exposure bright enough to read the subject.
695. **Color.** The subject's colors and the background colors as separate fields: sage green, dark amber, pale oak, white.
706. **Composition.** Crop, what the frame cuts off, and what stays sharp. One scene.
71
72Write prose that describes one photograph. A line that reads like an instruction ("make the coat darker") describes an attribute of that single picture; the model has no before-and-after to work from.
73
74## Say the thing you want to see
75
76Describe the material. "Brushed steel with fine horizontal grain" gives the model a surface to render, while "not shiny" gives it nothing to draw.
77
78A long avoid list is easy to ignore, and it spends the prompt on objects that then show up anyway. Keep a constraint only when it is a count or a specific object, and pair it with the thing you want: "one stainless spoon resting on the saucer."
79
80Name each object as what it is. A plate, a bowl, and an enameled skillet are different things, and so are a tote, a satchel, and a backpack. When the distinction matters, describe the feature that makes it that object: for a skillet, a cream enamel wall rising around the food and a handle cropped by the frame. A thin brown line on a ceramic rim reads as a plate.
81
82State texture once, physically. Repeated texture words get painted onto the wrong surface: cottage-cheese curds turn into a pebbled skin on the wrap that holds them, Parmesan flakes turn into paper squares, and potato chunks climb out of a frittata to sit on top as garnish.
83
84Ask for light that leaves the subject readable. "Bright and vivid, hard sun, flash, warm shadows with texture" holds. "Slightly underexposed" and "crushed shadows" pull the same picture dark. Leave out chromatic fringing, dust, and scratches; the model draws them as defects.
85
86## Generate, then edit
87
88Generate when there is no picture yet, or when the subject itself is wrong: it is a different object, a key element is missing, or the count is off.
89
90Edit when the subject and the layout are already right and one to three details need to change. Lead with those changes. Follow with one sentence that keeps the same subject, angle, crop, and prop placement.
91
92> Replace the metal watch strap with a brown leather strap with cream stitching. Keep the same wrist, the same shirt cuff, the same angle, and the same desk.
93
94An edit that opens with "keep everything" barely moves. An edit that pastes in a full new prompt restages the scene: the subject drifts, a second copy of a prop appears, and one object turns into a similar one, such as a plate into a pan.
95
96Change the words when a fix does not land. Repeating "more realistic" turns into a new texture on the wrong part of the picture. Point at the part instead: "the cut face shows separate russet potato chunks in moist egg," or "the leather shows creases where the strap bends."
97
98## How to tell a prompt worked
99
100Judge each picture against the original prompt, even after several rounds of edits. The question is whether this subject matches that prompt:
101
102* The subject is the one named.
103* Each element named in the prompt is visible, in the form the prompt describes.
104* The count matches.
105* Each object is the object the prompt named.
106* The picture is bright enough to see the subject.
107
108A matching background with the wrong subject is a miss. Save the prompt next to the image. On the next pass, change only the detail that failed and leave the rest of the original prompt in place, so the subject and the layout stay put.
109
110## Short prompts
111
112A single still outside a series needs four to six sentences: subject and details, then setting, then light, then crop.
113
114> A pair of white leather low-top sneakers with gum rubber soles, shot from a low three-quarter angle. The laces are loosely tied, the toe boxes show soft creases, and the left shoe sits slightly ahead of the right. They stand on pale gray concrete against a warm off-white wall. Hard morning sun from the right casts long, sharp shadows, with soft fill on the shaded side. 50mm product photograph, both shoes sharp, cropped just above the heel tabs.
115
116> A woman in her sixties with short silver hair and reading glasses pushed up on her head, laughing while she pots a small olive tree at a wooden workbench. Her hands are dusted with dark soil and her sleeves are rolled to the elbow. Terracotta pots and a steel trowel sit on the bench beside her. Soft window light from the left, bright and warm, with gentle shadows. 35mm photograph at eye level, framed from the waist up, her face in sharp focus.
117
118> A vegetarian Greek salad in a warm cream ceramic bowl, shot from a slight overhead angle. Cucumber, tomato, thick red onion, irregular feta crumbles, and wrinkled Kalamata olives overlap in olive oil, with oregano on the tomatoes. The bowl sits on butter-yellow linen over terracotta. A warm pita is partly visible at the right edge and a fork rests on the rim. Hard summer sun and on-camera flash, bright and vivid, with warm shadows. 35mm photograph, food filling the bowl, one frame.
119
120## Related
121
122* [Image Generation](/developers/model-capabilities/images/generation): request parameters for aspect ratio, resolution, and quality
123* [Image Editing](/developers/model-capabilities/images/editing): edit an existing image with a prompt
124* [Multi-Image Editing](/developers/model-capabilities/images/multi-image-editing): edit with several source images
