VGL turns a text prompt, or images plus a prompt, into a structured JSON description of a scene: objects, background, lighting, aesthetics, camera, and text. The result is a typed Pydantic model that an image model like FIBO takes as its prompt.
pip install bria-vglThe default LLM is Gemini through Google AI Studio. For other providers, install the extra:
pip install 'bria-vgl[vertex]' # Gemini on Vertex AI
pip install 'bria-vgl[bedrock]' # Claude on AWS Bedrock| Provider | llm= |
Set |
|---|---|---|
| Google AI Studio (default) | gemini/gemini-3.5-flash-lite |
GEMINI_API_KEY (get one) |
| Vertex AI | vertex_ai/gemini-3.5-flash-lite |
VERTEXAI_PROJECT, VERTEXAI_LOCATION, GOOGLE_APPLICATION_CREDENTIALS (a service account JSON) |
| AWS Bedrock | e.g. bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0 |
the usual AWS credentials and AWS_REGION_NAME |
llm takes any litellm model id, but the prompts are tuned for Gemini.
import bria_vgl
from bria_vgl.dialects.thales import Generate
scene = bria_vgl.create(Generate(prompt="a red fox in snow at dusk"))
print(scene.short_description)
print(scene.model_dump_json(indent=2, exclude_none=True))The image is a visual reference only. The VGL describes the scene the prompt asks for, not the image.
import bria_vgl
from bria_vgl.dialects.thales import Inspire
scene = bria_vgl.create(Inspire(prompt="the same fox, at the beach", image=fox))No prompt: the VGL describes the image itself.
from bria_vgl.dialects.thales import Caption
scene = bria_vgl.create(Caption(image=fox))No image: the prompt changes an existing VGL, and the fields it doesn't affect are kept.
from bria_vgl.dialects.thales import Generate, Refine
scene = bria_vgl.create(Generate(prompt="a cosy living room"))
night = bria_vgl.modify(Refine(prompt="make it night", input_vgl=scene))bria_vgl.create(Refine(...)) works too, and takes the create() options.
from PIL import Image
from bria_vgl.dialects.thales import EditImages
room = Image.open("room.jpg")
lamp = Image.open("lamp.jpg")
scene = bria_vgl.modify(EditImages(prompt="make it night", images=[room]))
scene = bria_vgl.modify(EditImages(prompt="put the lamp from <image_2> in <image_1>", images=[room, lamp]))
print(scene.edit_instruction)Up to 4 images. The prompt refers to them as <image_1> to <image_4>, in list order.
from bria_vgl.dialects.thales import EditImageWithMask
mask = Image.open("mask.png") # white is the area to change; same size as the image
scene = bria_vgl.modify(EditImageWithMask(prompt="replace it with a cat", image=room, mask=mask))If you have the VGL that an image was generated from, pass it as input_image_vgl. The edit then keeps everything the prompt doesn't change, rather than re-describing the image from scratch. vgl doesn't check that it matches the image.
scene = bria_vgl.create(Generate(prompt="a cosy living room"))
image = ... # generate the image from `scene` with FIBO
night = bria_vgl.modify(EditImages(prompt="make it night", images=[image], input_image_vgl=scene))Runnable versions are in examples/.
bria_vgl.create(payload, llm="vertex_ai/gemini-3.5-flash-lite", seed=7, style_preset_prompt="Muted film colours, soft grain.")
bria_vgl.modify(payload, llm=..., seed=...)llm: the litellm model id; see Authenticate.seed: makes a call repeatable, on models that accept one.style_preset_prompt: style guidelines added to the system prompt. Applies tocreateonly;modifyignores it.
create also takes overrides for the payload's defaults. Each is optional, and leaving it out keeps the default:
system_prompt: replaces the system prompt.{llm_input_schema}and{style_preset_block}in it are still filled.final_prompt: replaces the final (user) prompt. Its placeholders, such as{user_prompt}, are still filled.input_schema: the field guide filled into{llm_input_schema}.response_schema: the JSON schema the model must follow, in Gemini's format. Extra keys in the reply are dropped from the VGL.thinking_level: abria_vgl.ThinkingLevelor its string,"minimal","low","medium"or"high", on Gemini 3+. Anything else, or a level on an older Gemini, raisesValueErrorbefore the call. By default thinking is as low as the model allows.temperatureandmax_output_tokens: thinking tokens count againstmax_output_tokens, so raise it with a high thinking level.
A Gemini call that keeps failing (3 attempts) or hits a rate limit (429, not retried) moves to gemini-3.1-flash-lite on the same provider.
bria-vgl logs structured records: a constant message, with the data as extra fields on the record (model, duration_seconds, attempt, error, β¦). Use a formatter that emits record attributes (e.g. a JSON formatter) to see them; a plain %(message)s formatter shows only the message.
By default each module logs under the bria_vgl hierarchy (bria_vgl.gateway, bria_vgl.prompting, β¦); configure it the standard way, e.g. logging.getLogger("bria_vgl").setLevel(logging.INFO).
To route everything to your own logger, e.g. one carrying request context:
adapter = logging.LoggerAdapter(logging.getLogger("my_service"), {"request_id": rid}, merge_extra=True)
bria_vgl.set_logger(adapter) # set_logger(None) restores the defaultA plain LoggerAdapter replaces bria-vgl's extra fields with its own. Pass merge_extra=True (Python 3.13+) or override process() to keep both.
Everything bria-vgl raises inherits from bria_vgl.exceptions.VGLError, except a bad payload, which raises pydantic.ValidationError before any LLM call. The classes below all live in bria_vgl.exceptions.
| Error | Means |
|---|---|
AuthenticationError |
the provider rejected your credentials, e.g. a missing or wrong API key |
RateLimitError |
the provider returned 429 (quota exhausted), on the Gemini fallback too |
ContentFilteredError |
the provider's safety filter blocked the prompt or the reply |
LLMError |
any other provider failure, after retries and the fallback |
InvalidResponseError |
the model's reply isn't a valid VGL |
UnusableReplyError |
the model twice replied without a valid VGL, which reads as a refusal; it is both a ContentFilteredError and an InvalidResponseError |
MaxTokensError |
the model ran out of output tokens mid-reply |
PromptNotFoundError |
a bundled prompt is missing; a packaging fault, please report it |
A reply that isn't a valid VGL is asked for once more, with the next seed. A model that won't depict a prompt often answers with JSON that leaves out the scene, or with prose, rather than a filtered reply, so a second such reply raises UnusableReplyError.
A dialect is a small variant of VGL, with its own model, payloads, and prompts. The payload you import decides the dialect. vgl ships the Thales dialect: no aesthetic scores, and every edit states its change in edit_instruction.
- Best practices: how images are prepared, masks, and getting consistent results.
- Contributing