MCP conflicting_payload_fields: image_url or avatar_id, not both

Two tools on Sume's hosted MCP server take a still as the visual source: avatar-image-to-video_create and kling-motion-control_create. The payload accepts exactly one source, either image_url or an avatar reference, which is avatar_id or avatar_handle. If a model sends both, the call fails before any job exists, with the code conflicting_payload_fields.

The error, field by field

The message reads that the payload takes exactly one visual source: image_url, or avatar_id / avatar_handle, not both. The data holds the code, a path of image_url, a conflicts_with array of avatar_id and avatar_handle, and the tool name. Nothing ran, so no spend was held.

The opposite mistake has its own code. If the payload carries neither an image_url nor an avatar reference, the code is missing_payload_field with path image_url and next_action provide_image_url_or_avatar_reference. Blank strings count as absent, because the check trims the values.

Why a model sends both

Agents often fill an avatar_handle from memory of an earlier turn, then add an image_url the user just pasted. Both look valid to the model. The server refuses to guess which one the user meant, because the answer changes the face in the video. Pick one source and drop the other.

{
  "idempotency_key": "promo-17-motion-1",
  "payload": {
    "avatar_handle": "my-host",
    "motion_video_url": "https://cdn.example.com/dance.mp4",
    "duration_seconds": 8
  }
}

Instruction text that helps the agent

Tell the agent in its system prompt which source wins when both exist. For example: use the avatar when the user names a person who is saved, and use image_url only for a pasted image. Retrying with the same idempotency_key is safe after this error, because the first call did not run.

Keep the rest of the payload intact on the retry. The tools also demand fields of their own, such as a duration_seconds that matches the media length, so a corrected call can still fail on a different missing field. Read each error in turn rather than guessing.