InferenceClient image_to_image example fails for Qwen/Qwen-Image-Edit-2511 with fal-ai provider

Models
1

Hello,

I am trying to use the official Hugging Face API sample code for Qwen/Qwen-Image-Edit-2511 with the InferenceClient and fal-ai provider, but the example does not work as expected.

This is the exact code from the Hugging Face documentation / model page:

import os

from huggingface_hub import InferenceClient




client = InferenceClient(

    provider="fal-ai",

    api_key=os.environ["HF_TOKEN"],

)




with open("cat.jpg", "rb") as image_file:

   input_image = image_file.read()




# output is a PIL.Image object

image = client.image_to_image(

    input_image,

    prompt="Turn the cat into a tiger.",

    model="Qwen/Qwen-Image-Edit-2511",

)

Could you please clarify:

  1. Whether this example is still valid for Qwen/Qwen-Image-Edit-2511

  2. Whether there is an updated or working example for image editing with this model

  3. If this is a known issue with the fal-ai provider integration

Thank you very much for your help.

Environment:

  • OS: Win11

  • Python: 3.10

  • huggingface_hub: latest version

  • Provider: fal-ai

  • Model: Qwen/Qwen-Image-Edit-2511

Error message:
Traceback (most recent call last):
File “d:\huggingface\qwen_img_edit.py”, line 13, in
image = client.image_to_image(
^^^^^^^^^^^^^^^^^^^^^^
File “C:\Users\Administrator\AppData\Local\Programs\Python\Python312\Lib\site-packages\huggingface_hub\inference_client.py”, line 1327, in image_to_image
response = provider_helper.get_response(response, request_parameters)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File “C:\Users\Administrator\AppData\Local\Programs\Python\Python312\Lib\site-packages\huggingface_hub\inference_providers\fal_ai.py”, line 217, in get_response
url = _as_dict(output)[“images”][0][“url”]
~~~~~~~~~~~~~~~~^^^^^^^^^^
KeyError: ‘images’

1 Like
2

Hmm…

Your traceback is consistent with a response-shape mismatch: the Hugging Face fal-ai provider adapter is trying to read output["images"][0]["url"], but the JSON it actually got back does not contain an images key, so it throws KeyError: 'images'.

That “missing images” almost always means one of these happened:

  1. The request failed and the provider returned an error JSON (often keys like detail, error, message, etc.), not a normal success payload. The adapter then crashes while assuming success.
  2. The adapter sent the wrong input schema for this specific Fal endpoint, so Fal returned a schema/validation error, not an image result.

For Qwen Image Edit on Fal, the second explanation is very plausible, because this endpoint’s schema is not the same as many other Fal image-to-image endpoints.

1) Is the HF example still “valid” for Qwen/Qwen-Image-Edit-2511?

The example is still published in Hugging Face’s Inference Providers “Image to Image” docs and explicitly names Qwen/Qwen-Image-Edit-2511 with provider="fal-ai". (Hugging Face)

So: “valid” in the sense “officially shown.”
But: your failure indicates it can be currently broken in practice for this particular model-provider combination.

Key point to keep in mind: the InferenceClient method accepts **kwargs for image_to_image. (Hugging Face)
That is usually a hint that some providers/models need extra, provider-specific fields.

2) The most likely root cause in your case

A. Fal’s Qwen Image Edit endpoint expects image_urls (plural), not image_url (singular)

Fal’s documentation for the Qwen image edit endpoint shows an input field named image_urls (a list) and an output that includes images (a list of images). (fal.ai)

But many other Fal image-to-image endpoints use a singular image_url input. For example, Fal’s Recraft V3 image-to-image docs use image_url (singular).

So there is a real schema split on Fal:

  • some models: image_url
  • Qwen Image Edit (this one): image_urls

If the Hugging Face Fal adapter sends image_url to a model that requires image_urls, Fal will typically return a validation error JSON. That error JSON will not have images, so the adapter crashes with KeyError: 'images'.

This matches your stack trace exactly.

B. Your runtime environment looks different than you think

You wrote “Python 3.10,” but the traceback path contains Python312\Lib\site-packages\.... That suggests you executed the script under Python 3.12, not 3.10.

This does not directly cause KeyError: 'images', but it matters because:

  • you may be upgrading huggingface_hub in one Python install and running another
  • behavior can differ across versions

3) Concrete fixes and workarounds

Step 0. Verify you are upgrading the same Python you are running (Windows)

Run these in the same terminal you use to run the script:

python --version
python -m pip show huggingface_hub
python -m pip show pillow

If python --version prints 3.12, then your “Python 3.10” environment is not the one executing.

Step 1. Upgrade to the newest huggingface_hub (important)

The library is actively changing. Current docs show versioned pages up to v1.2.4, and PyPI shows recent releases. (PyPI)

Upgrade using:

python -m pip install -U huggingface_hub pillow

Then re-run. If the Hugging Face team already patched Fal’s Qwen schema handling, this alone can fix it.

Step 2. Try passing the provider-specific field (image_urls) via **kwargs

InferenceClient.image_to_image supports **kwargs. (Hugging Face)
If the Fal adapter merges unknown kwargs into the outgoing payload (common pattern), you can force the correct schema.

The trick is: you need an image_urls list, usually containing a data URL.

import os, base64
from huggingface_hub import InferenceClient

client = InferenceClient(provider="fal-ai", api_key=os.environ["HF_TOKEN"])

with open("cat.jpg", "rb") as f:
    img_bytes = f.read()

data_url = "data:image/jpeg;base64," + base64.b64encode(img_bytes).decode("utf-8")

# Key idea: provide image_urls=[...]
image = client.image_to_image(
    img_bytes,
    prompt="Turn the cat into a tiger.",
    model="Qwen/Qwen-Image-Edit-2511",
    image_urls=[data_url],
)

Why this is reasonable:

  • Fal’s Qwen endpoint expects image_urls (fal.ai)
  • HF’s client allows extra kwargs (Hugging Face)

If this works, it strongly confirms the bug is a payload-schema mismatch in the adapter’s default behavior.

Step 3. Reliable workaround: call Fal directly using Fal’s own schema

If you need a “works now” path regardless of Hugging Face adapter quirks, use Fal directly with the schema shown in Fal docs (image_urls). (fal.ai)

Even if you keep using Hugging Face for discovery, Fal is the one actually hosting this endpoint.

A minimal direct HTTP approach (schema-focused) looks like this conceptually:

  • send prompt and image_urls to Fal’s Qwen endpoint
  • receive JSON with images: [{url: ...}]
  • download the image bytes from that URL

Fal’s Qwen docs show that images is the returned field. (fal.ai)

I am not pasting Fal authentication details here because it depends on whether you want:

  • billing/auth through Hugging Face Inference Providers, or
  • billing/auth through Fal

But schema-wise, image_urls in, images out is the key.

4) Is this a known issue with the fal-ai provider integration?

What I can say with evidence:

  • Hugging Face’s official Image-to-Image Inference Providers page shows the exact code you used for Qwen/Qwen-Image-Edit-2511. (Hugging Face)
  • Fal’s Qwen endpoint schema differs from many other Fal image-to-image models (image_urls vs image_url). (fal.ai)
  • Your crash is consistent with “adapter expected a success payload with images, but received a different JSON.”

What I cannot honestly claim:

  • I did not find, within the limited browsing budget here, a single definitive public issue thread that mentions this exact KeyError: 'images' + this exact model ID.

So treat it as “very likely an integration edge case,” not “confirmed known bug,” unless you locate an upstream issue/PR that matches.

If you report it upstream, include this minimal diagnosis:

  • Fal Qwen Image Edit uses image_urls (list). (fal.ai)
  • Hugging Face Fal adapter appears to send image_url (singular) for image-to-image by default (common across other Fal models like Recraft).
  • Result: Fal returns an error JSON without images, adapter crashes with KeyError: 'images'.

5) Good reference material (high-signal)

I am listing items you can click via the citations:

  • Hugging Face Inference Providers “Image to Image” task doc (includes your exact snippet, plus task-level API spec). (Hugging Face)
  • Hugging Face InferenceClient reference showing image_to_image(..., **kwargs) support (important for provider-specific overrides). (Hugging Face)
  • Fal Qwen Image Edit endpoint schema (image_urls input, images output). (fal.ai)
  • Fal Recraft image-to-image schema (image_url singular), illustrating why a “one-size-fits-all” adapter can break.

Practical “do this now” path for your machine

  1. Confirm the interpreter you run is the interpreter you upgrade (python --version, python -m pip show huggingface_hub).
  2. Upgrade huggingface_hub and retry.
  3. If still failing, try the image_urls=[data_url] override.
  4. If you need immediate reliability, call Fal with its native schema (image_urls), then download from images[0].url.

Summary

  • Your error means the adapter expected output["images"] but got a different JSON.
  • The top suspect is a schema mismatch: Fal Qwen Image Edit expects image_urls (plural). (fal.ai)
  • Try upgrading first, then try passing image_urls via **kwargs. (Hugging Face)
  • If you need guaranteed success, use Fal’s native schema directly.
1 Like
3

It Works well.
Thank you!

1 Like
4

This topic was automatically closed 12 hours after the last reply. New replies are no longer allowed.