Captioning
Bitcrush Studio gives you several ways to create, organise, and maintain captions across your dataset. You can write captions manually, generate natural-language captions using a vision-language model, or let Studio build tag-style captions automatically from the information already associated with each image.
Studio supports multiple caption styles because modern DiT models, such as Flux Klein, Z-Image, and Anima, are often trained using a mixture of natural-language descriptions and structured tags. You can control how these captions are generated, how Studio classifies them, and which information is passed to the captioning model.
Studio supports three caption styles:
- Descriptive: Longer, detailed natural-language captions.
- Short: Concise natural-language captions.
- Tags: Comma-separated or tag-based captions, such as Danbooru-style captions.
You can customise the length threshold used to distinguish between descriptive and short captions in Application Settings, accessible from the top-right corner of Studio.
Incoming natural-language captions are analysed automatically and classified as either descriptive or short. This applies whether the caption was:
- Written manually, such as through Gallery View.
- Generated by a VLM using the Caption Tool.
- Imported from an existing caption file.
Tag-style captions are handled separately. Studio generates and updates them automatically in the background using the image's metadata and any tags added through Bitcrush Studio. This happens as part of the Background Sync process and can be customised in Application Settings.
Studio stores each caption as a separate line in the image's caption file. OneTrainer follows the same convention and treats each line as a separate caption. Other training tools may interpret caption files differently, so check the documentation for your chosen training tool before beginning a large training run.
Background Sync keeps the information associated with your images up to date without requiring you to regenerate every caption manually.
As part of this process, Studio can build tag-style captions from:
- Metadata associated with the image.
- Tags added or approved within Bitcrush Studio.
- Other supported image attributes available to Studio.
These tag-style captions are generated automatically in the background. They do not need to be requested from a VLM through the Caption Tool.
You can customise how Background Sync generates and updates tag-style captions in Application Settings.
The Caption Tool generates natural-language captions using either a cloud-based API or a locally hosted vision-language model.
The Caption Tool supports OpenAI-compatible endpoints from providers such as OpenRouter, Alibaba Cloud, OpenAI, and others.
Most cloud providers require an API key, which you can obtain from the provider. API keys entered into Studio are stored using the secure credential storage provided by your operating system.
Because processing takes place remotely, the practical batch size is mainly limited by your network connection, the provider's rate limits, and the amount of data being uploaded. A batch size of up to 64 is often practical, although the best setting will vary between providers.
You can also use an OpenAI-compatible local server, such as LM Studio, for local processing. You must first configure and start the server within LM Studio. See LM Studio's server documentation for instructions on exposing a local OpenAI-compatible endpoint.
Studio attempts to resolve known endpoints automatically. If a compatible endpoint is not detected or does not appear as expected, please raise an issue and include the provider name and endpoint format.
The Caption Tool also supports the Google Gemini API, allowing you to use compatible Gemini and Gemma models.
Note: Some providers and models do not support configurable reasoning effort. Others may use a different parameter name or reject the setting entirely. In these cases, attempting to disable or adjust reasoning effort may return an API error.
The Transformers backend uses Hugging Face Transformers to load compatible vision-language models directly onto your GPU.
Model files are downloaded automatically from Hugging Face when required. Some restricted or gated models may require a Hugging Face access token before they can be downloaded.
VRAM usage depends on the selected model, precision, quantisation settings, image resolution, and batch size.
The Llama.cpp backend provides experimental support for loading compatible local .gguf vision-language models.
Compatibility varies between models, particularly when a model requires a separate vision projector or uses an unsupported multimodal architecture.
Prompt Builder lets you control the instructions sent to the VLM for each image.
You can configure two kinds of prompts:
- Base Prompts: The main captioning instruction. Studio randomly selects one base prompt for each image.
- Variable Prompts: Optional instructions appended to the selected base prompt. Studio selects a random number of these according to your configured minimum and maximum values.
This introduces controlled variation into a captioning run. For example, one image may ask the model to describe the camera angle, while another may ask it to identify the shot type.
For each image, Studio:
- Selects one base prompt at random.
- Selects a random number of variable prompts within your configured minimum and maximum.
- Replaces any prompt variables with information from the current image.
- Sends the completed prompt and image to the selected VLM.
Prompt variables are placeholders that Studio replaces with information from the current image before sending the prompt to the VLM.
| Variable | What Studio inserts | Why you might use it |
|---|---|---|
{filename} |
The filename of the image currently being captioned. | Useful when filenames contain subject names, locations, sequence labels, or dataset categories that may help the model understand the image. |
{metadata} |
The metadata and Studio tags currently associated with the image. | Gives the model extra context and can help it preserve existing classifications or approved tags. |
{caption} |
The image's existing caption text, when one is available. | Lets the model expand, shorten, rewrite, correct, or preserve information from an existing caption. |
These variables are optional. Studio only inserts information that you explicitly reference in the prompt.
For example:
Write a detailed, descriptive caption for this image.
Filename: {filename}
Tags: {metadata}
Existing Caption (if present): {caption}
Include information about the camera angle.
Before sending the request, Studio replaces {filename}, {metadata}, and {caption} with the values belonging to that image.
A second image might receive a different base prompt and variable prompt:
Write a concise caption for this image, no more than 2 short sentences.
Filename: {filename}
Tags: {metadata}
Existing Caption (if present): {caption}
Include whether the image is a close-up, medium shot, or another shot type.
The Descriptive, Short, or Tag dropdown identifies the type of caption that a prompt configuration is intended to produce.
It does not force the returned text to be classified as that caption type. Incoming captions are still analysed using Studio's normal caption classification rules.
The selected type is mainly used by the Caption New Files & Missing Caption Types strategy. It tells Studio which missing caption type the prompt is intended to generate.
For example:
- An image with only a short caption can be sent to generate a descriptive caption.
- An image with only a descriptive caption can be sent to generate a short caption.
- An image without the requested caption type can be included without overwriting the caption types it already has.
Tag-style captions generated through Background Sync are not treated as natural-language captions by the Caption Tool. An image containing only a tag-style caption is therefore still considered to be missing both a descriptive and a short caption, and remains eligible for natural-language captioning.
-
System Prompt: Controls the higher-level instructions given to the VLM. You can use it to define the model's role, expected behaviour, formatting rules, or restrictions.
-
Max Tokens: Limits the maximum output token budget available to the model. Setting this too low may cause captions to be truncated. Depending on the provider and model, reasoning or thinking tokens may also consume part of this budget.
-
Temperature: Controls variation in the model's responses. Lower values generally produce more consistent captions, while higher values allow more varied or creative wording. Values between approximately
0.9and1.1often work well with frontier models, although the ideal value depends on the selected model and captioning task. -
Fallback Models: Defines one or more alternative models that Studio can try when the primary model fails to produce a caption. This may happen because the model refuses the image, the provider returns an error, the request times out, or the response does not contain a usable caption. Fallback models are attempted in the order shown.