Create an AI avatar from profile traits: the props input

To create an avatar from structured traits, call POST /v1/avatar-1.0/generate with input.type set to props. The documented example sets ethnicity, sex and age. In the docs this is called the Profile input, and it exists for apps that already hold profile details and would rather pass fields than write a prompt.

Source: Create new avatar and the API reference.

What does the request look like?

The body has a top-level avatar_handle plus an input union. The handle may include a leading @; Sume stores it without it.

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-profile-001" \
  -d '{
    "avatar_handle": "product_host",
    "input": {
      "type": "props",
      "ethnicity": "Asian",
      "sex": "female",
      "age": 28
    }
  }'

How do the three inputs differ?

Every request is job-backed: Sume returns a job, you poll it, and when it completes the avatar becomes a reusable resource in your workspace.

What does the docs example not promise?

The only traits shown are ethnicity, sex and age. The docs do not publish the full list of allowed values or any further fields, so check the live OpenAPI schema before building a form around them, and do not assume extra knobs such as hair or clothing exist. If you need that kind of detail, use the prompt input and say it in words, which is covered in how to write an AI avatar prompt.

What happens after the avatar is ready?

Use the handle on POST /v1/avatar-1.0/talking-video. One handle serves every later video, so the traits are set once; see creating a reusable avatar for the handle-naming habits that keep this tidy. List what you have with GET /v1/avatar-1.0/avatars.

When is the props input the wrong choice?

Use a prompt when the look matters in detail: wardrobe, setting, hair, mood. Use a photo when the avatar must resemble a specific person who has agreed to it; the photo input requires a fetchable public HTTPS image, and Sume rejects localhost, private-network, non-HTTPS and non-image URLs before generation. For the rules, see reference image URL rules.

Props is best for generated spokespeople in bulk, such as a set of presenters for different audiences, where a form in your own app maps cleanly to three fields and you do not want to maintain prompt wording.

How do I check the result?

Poll the creation job until it is completed, then fetch its result and read the avatar resource. Look at the avatar before you spend on videos: a handle you do not like is cheaper to replace than ten finished clips. If it is wrong, create a new avatar with a new handle and different input rather than reusing the handle, since the docs do not describe editing an existing one.