invoke-ai/InvokeAI · error · ExternalProviderRequestError

OpenAI image edits require at least one image (init image or

Error message

OpenAI image edits require at least one image (init image or reference image)

What it means

ExternalProviderRequestError raised when the OpenAI provider is about to call the /v1/images/edits endpoint but the request carries no source images at all. Edits mode is selected whenever request.mode != 'txt2img' or reference_images exist, yet the collected images list (init_image plus reference_images) is empty — e.g. an img2img/variation job whose image inputs were never populated. OpenAI's edits API requires at least one image, so the provider fails fast with this actionable message.

Source

Thrown at invokeai/app/services/external_generation/providers/openai.py:76

                payload["response_format"] = "b64_json"
            if is_gpt_image:
                if opts.get("quality") and opts["quality"] != "auto":
                    payload["quality"] = opts["quality"]
                if opts.get("background") and opts["background"] != "auto":
                    payload["background"] = opts["background"]
            response = requests.post(
                f"{base_url}/v1/images/generations",
                headers=headers,
                json=payload,
                timeout=timeout,
            )
        else:
            images: list[PILImageType] = []
            if request.init_image is not None:
                images.append(request.init_image)
            images.extend(reference.image for reference in request.reference_images)
            if not images:
                raise ExternalProviderRequestError(
                    "OpenAI image edits require at least one image (init image or reference image)"
                )

            files: list[tuple[str, tuple[str, io.BytesIO, str]]] = []
            image_field_name = "image" if len(images) == 1 else "image[]"
            for index, image in enumerate(images):
                image_buffer = io.BytesIO()
                image.save(image_buffer, format="PNG")
                image_buffer.seek(0)
                files.append((image_field_name, (f"image_{index}.png", image_buffer, "image/png")))

            if request.mask_image is not None:
                mask_buffer = io.BytesIO()
                request.mask_image.save(mask_buffer, format="PNG")
                mask_buffer.seek(0)
                files.append(("mask", ("mask.png", mask_buffer, "image/png")))

            data: dict[str, object] = {

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Provide an init image (request.init_image) or at least one reference image before invoking the OpenAI provider in edit mode.
2. Switch the request to mode 'txt2img' with no reference_images if pure text-to-image is intended, so the generations endpoint is used.
3. Check the calling workflow/graph: ensure the image input node is connected and the image data survives serialization.
4. Add a pre-submit validation in your integration that mirrors this check: if mode != 'txt2img' and not (init_image or reference_images): reject.

Example fix

// before: edit-mode request without any image
request = ExternalGenerationRequest(mode="edit", prompt="...", init_image=None, reference_images=[])
result = provider.generate(request)
// after: fall back to txt2img when no image is supplied
if request.mode != "txt2img" and request.init_image is None and not request.reference_images:
    request = replace(request, mode="txt2img")
result = provider.generate(request)

def validate_openai_edit_request(request) -> None:
    if request.mode != "txt2img":
        has_images = request.init_image is not None or bool(request.reference_images)
        if not has_images:
            raise ValueError("Edit mode requires an init image or at least one reference image")

def can_edit(request) -> bool:
    return request.init_image is not None or len(request.reference_images) > 0

try:
    result = provider.generate(request)
except ExternalProviderRequestError as e:
    if "require at least one image" in str(e):
        request = replace(request, mode="txt2img")  # degrade gracefully
        result = provider.generate(request)
    else:
        raise

When it happens

Trigger: use_edits_endpoint is True (mode != 'txt2img' or reference_images non-empty) but request.init_image is None and request.reference_images resolves to zero usable images — e.g. a workflow node set to img2img without connecting an init image, reference_images containing only entries filtered out upstream, or mode mislabeled by the caller.

Common situations: User selects an edit/img2img OpenAI model but leaves the image input unconnected; a queue retry loses the binary init image; caller sets mode='edit' programmatically assuming references are optional; UI passes reference metadata without the actual PIL images.

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

• At least one Krea-2 conditioning is required.
• No external provider config fields provided
• str(e)
• str(e) (ValueError from user service update, e.g. LastAdmini
• Current password is required to set a new password

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/7ad217a23afbfd8f. Report an issue: GitHub.