BerriAI/litellm · error · ValueError

Vertex AI Imagen image edit requires at least one reference

Error message

Vertex AI Imagen image edit requires at least one reference image.

What it means

Imagen image editing is reference-image driven: every request instance must contain at least one referenceImage (the source photo to edit). The transformer checks the image argument first and raises immediately when it is None, before any byte reading or prompt validation. This mirrors the API contract — unlike Gemini edit, Imagen edit cannot proceed with prompt-only input.

Source

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

        if api_base:
            base_url = api_base.rstrip("/")
        else:
            base_url = get_vertex_base_url(vertex_location)

        return f"{base_url}/v1/projects/{vertex_project}/locations/{vertex_location}/publishers/google/models/{model_name}:predict"

    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 = {

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Always pass the source image (bytes, BytesIO, binary file object, or list of them) when the model is a vertex_ai/imagen-* edit model
2. Validate presence at the request boundary: reject requests without an image before they reach litellm
3. If no source image exists, switch to litellm.image_generation (prompt-only) instead of image_edit

Example fix

# before
resp = litellm.image_edit(
    model='vertex_ai/imagen-3.0-capability-001',
    prompt='make it night',
)  # image omitted -> raises

# after
with open('street.png', 'rb') as f:
    resp = litellm.image_edit(
        model='vertex_ai/imagen-3.0-capability-001',
        prompt='make it night',
        image=f.read(),
    )

if image is None:
    raise ValueError('an edit request requires the source image')
# then call litellm.image_edit(..., image=image, prompt=prompt)

try:
    resp = litellm.image_edit(model='vertex_ai/imagen-3.0-capability-001', prompt=p, image=image)
except ValueError as e:
    if 'requires at least one reference image' in str(e):
        return bad_request('source image is required for imagen edit')
    raise

When it happens

Trigger: litellm.image_edit(model='vertex_ai/imagen-3.0-capability-001', prompt='make it night') with the image kwarg omitted or explicitly None; calling through the OpenAI-compatible images/edits endpoint with no image file in the multipart form.

Common situations: Reusing Gemini-edit code paths (where the same call shape exists) against an Imagen model; multipart proxy routes that forward an empty file field; API clients built against OpenAI where image is validated lazily.

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 a prompt.
• 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/a44d57d69587b0de. Report an issue: GitHub.