Avatar create 400: removed name and file fields and their replacements

If your avatar request on Sume returns 400 with a details.fields list, you are sending removed fields. On /v1/models/sume/avatar-1.0/generate/runs, name has been replaced by avatar_handle, and file has been replaced by input.image_url. The API reports every removed field it finds in one response, each as {field, replacement}, so you can fix them in one pass instead of one error at a time.

The current contract is on Create new avatar, read 2026-10-05, and the reference route is POST /v1/avatar-1.0/generate.

Old field to new field

The mapping is small enough to keep in a table. Both fields are rejected, not silently translated, so an old client fails loudly instead of creating an avatar with an unexpected handle.

What happens with name alone

A request that sends only a name and no handle is rejected as invalid_request. A legacy name is tolerated only when a handle is also present, which is a migration aid and not something to rely on. A missing handle is always an error, because the handle is how the avatar is addressed in later video calls.

The point of rejecting rather than translating is traceability. If the API quietly mapped name to a handle, two clients could create avatars with handles neither team chose. A hard error forces one explicit choice and keeps the handle stable for every later talking-video call.

A common upgrade path is a thin wrapper in your own code that builds the request body. Change the wrapper once, and every caller gets the new fields. Keep the old call sites out of the wrapper's signature so nobody passes name by accident.

The migrated request

Below is the migrated body. The request is the same avatar, written with the current fields. The Idempotency-Key is a header and does not go in the body.

curl -X POST https://api.sume.com/v1/avatar-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: migrate-presenter-01" \
  -d '{
    "avatar_handle": "presenter_01",
    "input": {
      "type": "photo",
      "image_url": "https://assets.example.com/headshot.jpg"
    }
  }'

Handle rules still apply

Handles follow Instagram-style rules, and the sume_ prefix is reserved for system avatars, so you cannot create a handle that starts with it. A bad handle on the avatar list filter returns invalid_request with details.field: handle and rule: instagram_style. The detailed rules are in the handle rules post.

Two more details from the docs are worth checking while you migrate. Avatar video requests send avatar_handle at the top level as well, so the same word now names the avatar in both the create and the video call. And the compatibility routes GET /v1/avatars and GET /v1/avatars/:id return the same shape as /v1/avatar-1.0/avatars, so a list call written against either one keeps working.

How to handle it in a client

For client code, treat details.fields as a list and loop over it. Do not read only the first item. In a typed client, give the field a {field: string; replacement: string}[] type and show every pair to the developer. Then run the migrated request once with a fresh idempotency key, since the rejected attempts created no avatar and no job.

If the new request fails on the photo itself, you have moved past this error: see the photo error handler for the codes that follow.

A short migration checklist helps. Search your code for name: and file: in avatar calls. Replace each with the new field. Run one create against a photo you intend to keep, since a successful create is a $0.95 job. Confirm the avatar appears in the list under the handle you chose, and then change your video calls to use that same handle.