Input Gate NotesWhat a video model will accept, and why the rejection usually happens before any compute runs.

A validator you can write from one error message

The most common rejection in Wan 3.0 arrives as this, and it arrives before any compute has run:

{
  "code": "InvalidParameter",
  "message": "The two modes are mutually exclusive. Do not pass reference_xx and first_frame/last_frame at the same time."
}

Read as an error it is annoying. Read as documentation it is unusually generous, because it names both sides of the rule, and once you have both sides you can write the whole validator without reading anything else.

The two sets

One family is reference: reference_image, reference_video, reference_audio, file, link.

The other is keyframe: first_frame, last_frame.

The rule is that a request may draw from one set or the other, never both.

Why it is not a bug to route around

Every few weeks somebody proposes working around this by sending the keyframe first and then a second request with the references, which does not do what they want and costs twice.

The two families are asking for different jobs.

Keyframes say: the picture starts here, and possibly ends there; invent the middle. That is closer to interpolation than to generation. The endpoints are fixed and the model's freedom is the path between them.

References say: here is a cast, a palette and a mood; work out the shot yourself. The model's freedom is the whole frame; what is fixed is identity.

A single pass cannot simultaneously be pinned at both ends and freely composed from a pile of supplied material. The constraint is in the shape of the job, not in the API layer, which is why no gateway that wraps this model has removed it.

So the fix is a decision, made before the request is built:

• If the opening image is non-negotiable, this is a keyframe job, and your references have to become words in the prompt. The tradeoffs of driving a shot from a single photograph are worth understanding before you commit to it, because the first frame constrains frame one and not the shot.
• If the cast is non-negotiable, this is a reference job, and you describe the opening instead of uploading it.

Two smaller versions of the same rule

The same shape shows up twice more, and both are easy to miss because the documentation states them in passing:

• file and link are mutually exclusive. One document or one URL.
• There is exactly one of each per job. Not one of each per family — one, total.

What the validator looks like

Four lines, and it should run in the client before the request is serialised:

1. Partition the supplied keys into the two sets.
2. If both sets are non-empty, refuse, and say which keys collided.
3. If file and link are both present, refuse.
4. If either appears more than once, refuse.

The part worth spending effort on is step 2's message. The API tells you that the modes are exclusive; it does not tell you that you attached a last frame in a previous session and forgot. Naming the offending keys turns a support ticket into a five-second fix.

The thing this rule is actually protecting

If you only remember one sentence from this page, make it this one: the input family you choose is a statement about which kind of consistency you are buying. Keyframes buy you consistency with a specific image. References buy you consistency of identity across a whole take. They are both called "consistency" and they are not interchangeable, and choosing between them is the first real decision in the job — earlier than the prompt, earlier than the length, earlier than the resolution.

Limits and error strings on this page were read from Alibaba Cloud Model Studio's Wan 3.0 API reference on 2026-08-25.