Reference roles
When you give a model several reference pictures, it helps to say what each one is for: copy this logo exactly, borrow the style of that one, follow the layout of a third. The reference_assets field does this. Each reference gets a role, and Go Bananas describes each role to the model in the prompt.
reference_assets works on generate_image, start_generation and POST /api/images. On the Prompt page in the console you can label reference pictures the same way.
Example
{
"prompt": "launch poster for our new shoe",
"reference_assets": [
{ "role": "logo", "image_id": 12 },
{ "role": "style", "image_id": 40, "weight": 0.8 },
{ "role": "product", "product_id": 3, "notes": "show the left side" }
]
}Roles
| Role | What the model is told |
|---|---|
logo | Reproduce it exactly; do not alter its shapes, colours or text |
style | Match its palette, lighting and rendering, not its content |
composition | Follow its layout, framing and arrangement, not its subject or style |
template | A high-priority layout: follow its structure, placement and proportions closely, changing only what the prompt asks for |
character | Keep the character's face, hair and outfit exactly the same |
product | Keep the product's design, colours, materials, textures and proportions exact |
start_frame, end_frame, video_reference and audio_reference are reserved for future video workflows. They are rejected for now.
All six image roles work with every model.
Fields
Each entry has a role and exactly one source:
| Source | Description |
|---|---|
image_id | An image in your workspace's gallery |
image_url | A public http(s) image URL |
r2_key | The storage key of an image in your workspace |
character_id | A saved character. Only with role character |
product_id | A saved product reference. Only with role product |
reference_group_id | A saved reference group. Every image in the group takes this role |
Optional fields:
| Field | Description |
|---|---|
weight | 0 to 1. It only changes the wording: 0.75 or more asks for a strong, high-priority reference; 0.35 or less asks for a light, loose influence; anything else is standard |
notes | Up to 300 characters of extra guidance for this reference, added to the prompt |
scope | Role character only: face, wardrobe or full (the default). It only changes the wording. See Character scope |
Character scope
A character can be built from two pictures: a face plate and an outfit plate. scope on a character reference says what each picture gives:
| Scope | What the model is told |
|---|---|
face | This picture is the face plate: it gives the face and bone structure only (skull shape, jaw, chin, cheekbones, eye shape and spacing, brow shape, nose, lips and ear shape) |
wardrobe | This picture is the outfit plate: it gives the wardrobe, footwear, jewellery, hair colour and cut, build and proportions, and every tattoo, scar and body marking |
full | The standard character wording: keep the face, hair and outfit exactly the same. Leaving scope out does the same |
When a request has at least one face plate and one outfit plate, one more line says that hair styling, jewellery, clothing and skin markings all come from the outfit plate. It is there so a chest-up face plate's own hair and earrings do not carry into the result.
{
"prompt": "the same woman walking through a rainy market",
"reference_assets": [
{ "role": "character", "image_id": 12, "scope": "face" },
{ "role": "character", "image_id": 34, "scope": "wardrobe" }
]
}scope is set in the request. The Prompt page does not offer it.
Identity kit
The reference sheets use scope to build a set of plates for a recurring character:
- Make a
face-platefrom text. - Make an
outfit-platewith the face plate as{ "role": "character", "image_id": <face plate>, "scope": "face" }. - Make a
three-panelsheet with the face plate (scope: "face") and the outfit plate (scope: "wardrobe").
Each later step is given the face plate, so the face is copied from it rather than drawn again from the description.
Rules
- 1 to 16 entries per request.
- Typed references are attached after any other references in the request (such as
reference_images, characters or products), numbered in order. - The total number of reference images must fit the model: 14 for Gemini models, 16 for OpenAI models. Go Bananas rejects a request that is over the limit rather than dropping images.
- Images given by
image_id,image_urlorr2_keymust be at least 512 x 512 pixels. Stored images must belong to your workspace. OAuth clients also need read access to any character, product or reference group they name. - A request with a mistake in
reference_assets, such as two sources in one entry, an unknown role orscopeon a role other thancharacter, is rejected with a400before anything is generated. reference_assetsalways uses a provider model. It does not run on a ChatGPT subscription.