BerriAI/litellm · error · ValueError

Vertex AI Imagen image edit requires a prompt.

Error message

Vertex AI Imagen image edit requires a prompt.

What it means

Every Imagen edit instance is {'prompt': ..., 'referenceImages': [...]}; the API has no prompt-less edit. After reference images are validated, the transformer checks prompt and raises if it is None (kwarg omitted). Note the check is strict None only — an empty string '' passes this local guard and is sent upstream, where Vertex AI decides.

Source

Thrown at litellm/llms/vertex_ai/image_edit/vertex_imagen_transformation.py:163

    def transform_image_edit_request(
        self,
        model: str,
        prompt: str | None,
        image: FileTypes | None,
        image_edit_optional_request_params: dict[str, Any],
        litellm_params: GenericLiteLLMParams,
        headers: dict,
    ) -> tuple[dict[str, Any], RequestFiles | None]:
        # Prepare reference images in the correct Imagen format
        if image is None:
            raise ValueError("Vertex AI Imagen image edit requires at least one reference image.")
        reference_images: Final = self._prepare_reference_images(image, image_edit_optional_request_params)
        if not reference_images:
            raise ValueError("Vertex AI Imagen image edit requires at least one reference image.")

        if prompt is None:
            raise ValueError("Vertex AI Imagen image edit requires a prompt.")

        # Correct Imagen instances format
        instances: Final = [{"prompt": prompt, "referenceImages": reference_images}]

        # Extract OpenAI parameters and set sensible defaults for Vertex AI-specific parameters
        sample_count: Final = image_edit_optional_request_params.get("sampleCount", 1)
        # Use sensible defaults for Vertex AI-specific parameters (not exposed to users)
        edit_mode: Final = "EDIT_MODE_INPAINT_INSERTION"  # Default edit mode
        base_steps: Final = 50  # Default number of steps

        # Imagen parameters with correct structure
        parameters: Final = {
            "sampleCount": sample_count,
            "editMode": edit_mode,
            "editConfig": {"baseSteps": base_steps},
        }

        # Set default values for Vertex AI-specific parameters (not configurable by users via OpenAI API)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Always send a non-empty instruction string as prompt for Imagen edits
2. Map empty UI input to a sensible default prompt instead of None (e.g. prompt or 'edit this image')
3. Validate prompt presence in your request schema (min_length=1) before calling litellm

Example fix

# before
resp = litellm.image_edit(
    model='vertex_ai/imagen-3.0-capability-001',
    image=open('cat.png', 'rb').read(),
)  # prompt omitted -> raises

# after
resp = litellm.image_edit(
    model='vertex_ai/imagen-3.0-capability-001',
    prompt='remove the background',
    image=open('cat.png', 'rb').read(),
)

if prompt is None:
    raise ValueError('imagen edit requires a prompt')
# pydantic: prompt: str = Field(min_length=1)

try:
    resp = litellm.image_edit(model='vertex_ai/imagen-3.0-capability-001', prompt=prompt, image=img)
except ValueError as e:
    if 'requires a prompt' in str(e):
        return bad_request('prompt is required')
    raise

When it happens

Trigger: litellm.image_edit(model='vertex_ai/imagen-...', image=f) with no prompt kwarg; a proxy route that forwards the file but drops an empty prompt field so it deserializes to None; prompt=prompt or None patterns that collapse '' to None.

Common situations: Treating prompt as optional because Gemini edit tolerates prompt=None; form handlers converting empty textarea values to None instead of ''; request models using Optional[str] defaults of None.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Vertex AI Imagen image edit requires at least one reference
• Vertex AI Gemini image edit requires at least one image.
• Max recursion depth {max_depth} reached while reading image
• Unsupported image type for Vertex AI Imagen image edit.
• Unsupported image input: plain string values are not accepte

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/232fb4ad3e052dc1. Report an issue: GitHub.