Sume Avatar API: canonical routes vs the legacy model-run aliases

New integrations should call POST /v1/avatar-1.0/generate to create an avatar and POST /v1/avatar-1.0/talking-video to render a talking video. The older model-run paths still work with the same body, but Sume's docs say to prefer the canonical routes. Face swap has only a model-run path, POST /v1/models/sume/avatar-face-swap/v1.0/runs.

Everything below is from the models overview, the API reference, Create new avatar and Generate avatar video.

What are all the Avatar routes?

Does the alias change the request body?

No. The docs describe the model-run aliases as sharing the same body contract. Avatar creation uses a top-level avatar_handle plus an input union (prompt, props or photo); avatar video uses avatar_handle plus exactly one of script or video_inputs. Switching from an alias to the canonical route is a URL change.

Why does POST /v1/avatars not work?

The reference notes that creating through POST /v1/avatars and POST /v1/avatar-videos is hidden. Those resource paths are for reading. Create through the canonical route or a model-run endpoint, then read the resource with GET. That is why the table above lists GET /v1/avatars as a compatibility read path only.

What about the older image-to-video route?

POST /v1/avatar-1.0/image-to-video is a deprecated alias: the docs point to POST /v1/veed/fabric-1.0, which takes the same body. That route is for a still plus audio, not for a handle plus a script; see Fabric versus the avatar route.

How should I choose in new code?

Use the canonical routes everywhere you can, keep the avatar handle stable, and send an Idempotency-Key on every paid submit. Poll with GET /v1/jobs/:id/status whichever route you used; jobs look the same. A worked example in Python lives in create a talking avatar using Python.

How do I migrate existing code?

Search your codebase for /v1/models/sume/avatar and /runs. For each hit, replace the URL with the canonical route from the table and leave the body untouched. Run one request against a test workspace, confirm the job envelope looks the same, and ship. Because the aliases remain supported, there is no deadline in the docs, but new code on the canonical routes avoids a later cleanup.

One caution: do not mix the face swap path into this migration. It has no canonical shortcut and stays on its model-run URL.

Where do I confirm the exact schemas?

The guides show examples; the live OpenAPI at https://api.sume.com/reference/json is the authority for field names, defaults and required fields. When a guide and a snippet in a blog post disagree, trust the schema. The docs also note that exact request and response shapes for previews live there rather than on the guide page.