BerriAI/litellm · error · ValueError

OUTPAINTING requires either a mask image or a mask prompt. P

Error message

OUTPAINTING requires either a mask image or a mask prompt. Pass mask=<file> or maskPrompt=<str> in the request.

What it means

For Amazon Nova Canvas image edits with explicit taskType='OUTPAINTING', the task-body builder requires a mask: either a mask image (OpenAI mask= parameter) or a maskPrompt string. If both mask_b64 and mask_prompt are None it raises this ValueError, because Bedrock's outPaintingParams API rejects requests without one of maskPrompt/maskImage.

Source

Thrown at litellm/llms/bedrock/image_edit/amazon_nova_canvas_image_edit_transformation.py:59

    *,
    image_b64: str,
    mask_b64: str | None,
    text: str,
    negative_text: str | None,
    similarity_strength: float | None,
    task_type: str | None,
    mask_prompt: str | None,
    out_painting_mode: str | None,
) -> dict[str, Any]:
    """Build InvokeModel body task section (without imageGenerationConfig)."""
    if task_type == "BACKGROUND_REMOVAL":
        return {
            "taskType": "BACKGROUND_REMOVAL",
            "backgroundRemovalParams": {"image": image_b64},
        }
    if task_type == "OUTPAINTING":
        if mask_prompt is None and mask_b64 is None:
            raise ValueError(
                "OUTPAINTING requires either a mask image or a mask prompt. "
                "Pass mask=<file> or maskPrompt=<str> in the request."
            )
        out_params: Final[dict[str, Any]] = {
            "image": image_b64,
            "text": text,
        }
        if mask_prompt is not None:
            out_params["maskPrompt"] = mask_prompt
        elif mask_b64 is not None:
            out_params["maskImage"] = mask_b64
        if negative_text is not None:
            out_params["negativeText"] = negative_text
        if out_painting_mode is not None:
            out_params["outPaintingMode"] = out_painting_mode
        return {
            "taskType": "OUTPAINTING",
            "outPaintingParams": out_params,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Add maskPrompt to the request's optional params: pass maskPrompt="the area to extend" (or taskType-appropriate mask description).
2. Or supply a mask image: include the OpenAI-compatible mask= file part, which LiteLLM base64-encodes to maskImage.
3. If you don't need outpainting, drop taskType so LiteLLM auto-routes (mask -> INPAINTING, else IMAGE_VARIATION).

Example fix

# before
resp = litellm.image_edit(
    model="bedrock/amazon.nova-canvas-v1:0",
    prompt="extend the scene",
    image=image_file,
    taskType="OUTPAINTING",  # no mask -> ValueError
)
# after
resp = litellm.image_edit(
    model="bedrock/amazon.nova-canvas-v1:0",
    prompt="extend the scene",
    image=image_file,
    taskType="OUTPAINTING",
    maskPrompt="everything outside the person",
)

def validate_outpainting(params: dict, mask_present: bool) -> None:
    if params.get("taskType") == "OUTPAINTING" and not (
        mask_present or params.get("maskPrompt")
    ):
        raise ValueError("OUTPAINTING needs mask= file or maskPrompt")

When it happens

Trigger: POST /v1/images/edits with model=nova-canvas*, optional_params taskType='OUTPAINTING', and neither a mask file part nor a maskPrompt in optional_params.

Common situations: Porting OpenAI images/edits code (which has no maskPrompt concept) to Nova Canvas with taskType set; forgetting that OUTPAINTING on Nova is stricter than OpenAI's optional mask; typo like mask_prompt passed at top level instead of inside optional params.

Related errors

• Unsupported Amazon Nova Canvas taskType: {task_type!r}. Use
• Amazon Nova Canvas INPAINTING requires either maskPrompt or
• Nova Canvas image edit requires an image input
• Nova Canvas image edit does not support tuple FileTypes. Pas
• Amazon Nova Canvas {task_type} requires a text prompt. Pass

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/8bc9db9195a86f7b. Report an issue: GitHub.