Avatar 1.0 API routes: canonical paths vs legacy aliases

For new integrations call POST /v1/avatar-1.0/generate to create an avatar and POST /v1/avatar-1.0/talking-video to make a talking video. The longer model-run paths and the legacy launch paths remain supported with the same request body, so existing code keeps working, but the docs say to prefer the canonical routes.

Talking-head and lip-sync ad variants are mostly many calls to the same two routes with different scripts, which makes it worth fixing the paths once.

Canonical route and aliases side by side

Reading resources has the same split. Prefer the Avatar 1.0 resource routes for listing and fetching avatars; the compatibility list and read routes return the same response shape. Avatar videos are read from /v1/avatar-videos, and previews live under /v1/avatar-video-previews.

Three ways to create the avatar

Avatar creation takes a top-level avatar_handle plus an input union with three types: a text prompt, a props profile (traits such as ethnicity, sex and age) and a photo reference. The handle may include a leading @; Sume stores it without the @. For a photo, image_url must be a fetchable public HTTPS image URL, and localhost, private-network, non-HTTPS and non-image URLs are rejected before generation is submitted.

Each request creates a job. Poll /v1/jobs/{id}/status, fetch /v1/jobs/{id}/result when it is completed, then use the handle in the talking-video call.

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: avatar-image-001" \
  -d '{
    "avatar_handle": "reference_presenter",
    "input": { "type": "photo", "image_url": "https://example.com/reference.png" }
  }'

One body for every variant

A talking video takes exactly one of script or video_inputs, an optional product_image and scene, quality of standard, plus (the default) or max, and an aspect_ratio of 1:1, 3:4, 9:16 (the default), 4:3 or 16:9. Estimated duration must land between 4 and 60 seconds. Send an Idempotency-Key on each create, and change the key when you change the script.

Keep one thin wrapper in your code that holds the base path, so a variant test is a loop over scripts rather than a set of hand-built URLs.