generation API empty image inputs: Treat no reference as an explicit workflow choice

The generation API empty image inputs case is valid under the current provider schemas when the value is an empty array. Each adapter defines imageInputs as an optional array of URL strings without a minimum array length. That validation fact is narrower than a guarantee about what any upstream model will produce.

Trace the empty array

The public routes map image_inputs ?? imageInputs. An empty snake case array is not null, so it wins over a nonempty camel case alias. The normalized provider parameters therefore contain an empty array even when the other spelling contains a reference.

The adapters inspect imageInputs?.[0] before adding image_url. With an empty array there is no first entry, so the ordinary mapping does not include that upstream reference field. An omitted reference has the same absence of an image_url through this mapping, although the saved normalized parameters can differ.

A null value behaves differently because alias fallback and schema validation happen in sequence. An array containing an empty string is different again: the entry is not a valid URL, so it fails the URL validator rather than meaning no reference.

Separate schema permission from product requirements

A product feature called animate this photo should require a selected reference in its own application logic. The gateway schemas do not enforce that feature-level condition. If the upload selection is lost and an empty array is sent, local schema acceptance does not establish that the user’s photo was used.

Store the chosen reference identifier and content hash with the application task. Before submission, compare that selection with the actual first URL in the serialized request. A thumbnail remaining in the interface is not sufficient evidence that the request still contains the image.

For a text-only creative workflow, make no reference an explicit selection. This avoids showing an old thumbnail from a previous task while the next request intentionally omits a source.

Review reset and removal actions

Test clearing a reference after selecting one. The UI, local draft, and serialized request should all agree on the absence. Then test switching from text-only to a workflow requiring a reference. The application should block submission until a valid source is selected again.

A syntactically valid URL does not establish fetchability, access permission, or immutable bytes. Those are separate checks in your asset pipeline. Keep them visible instead of treating URL validation as complete reference verification.

Acceptance evidence

Prepare fixtures for missing references, an empty array, one URL, an invalid entry, and two conflicting alias arrays. Record the expected first image mapping without calling a model. For features requiring a reference, verify that both missing and empty cases fail locally.

Continue with reference image handling, multiple reference inputs, and alias precedence before approving a shared uploader.

Continue with models and parameters

• Flux API key: two paths, and what changes after you have one
• Flux API parameters: every accepted value and what it costs
• Flux aspect ratio options: what it accepts and what it rejects
• Browse all models and parameters guides