Fabric request: image_url and avatar_handle together are not allowed

A VEED Fabric 1.0 request on Sume must name exactly one visual source: an image_url, or an avatar by avatar_id or avatar_handle. The models page says you cannot send the two sources together, and the API reference describes each field as mutually exclusive with the others (read 2026-10-09). If a body carries both, fix the body and resubmit; a retry with the same content will fail again.

The valid shapes

The same rule applies to Sume's MiniMax H3 Max Lip Sync route, which takes the same body, and to Kling motion control. Three requests cover the cases.

Which one to use

The models page recommends the image_url of a generated, inspected posed still as the preferred source for a person who speaks on camera. Use avatar_handle only when the user named that avatar. The point is control: a posed still you reviewed gives you the exact framing, while a handle resolves server-side to the avatar's identity still.

Everything else on the body is the same either way. audio_url must be a Sume-hosted URL (non-Sume hosts are rejected) under 10 MB, and duration_seconds is the measured audio length from 1 to 300. resolution is 480p or 720p, with 720p as the default. A 20-second track costs 20 x $0.1875 = $3.75 at 720p or 20 x $0.10 = $2.00 at 480p.

A pre-flight check

Validate on your side before you submit, so a mistake costs no reservation. Check that exactly one of the three visual fields is present, that the audio URL host is Sume's media host, that the file is under 10 MB, and that duration_seconds is a measured number, not a guess. Then send with an Idempotency-Key.

If a submit succeeds, store the job.id, poll GET /v1/jobs/:id/status, and fetch /result when it completes. Treat the first response as the record of the job, not the clip.

• One of: image_url, avatar_id, avatar_handle.
• audio_url on the Sume media host, under 10 MB.
• duration_seconds measured, 1 to 300.

Common ways the second source sneaks in

Two sources often appear through code, not by choice. A shared template that always sets image_url gets an avatar_handle added by a later step. A client library that merges default fields into every body does the same. A no-code tool that maps all columns of a row into the request adds a stale image column. The fix is the same: build the body from the route's schema, with one visual field, and drop the rest before sending.

Log the final body, minus secrets, next to the response's request id. When something fails, the id lets Sume support find the request, and the body tells you which field was extra.