2026-09-25Sume Avatar 1.0

How to create a reusable AI avatar with the Sume Avatar 1.0 API

Send POST /v1/avatar-1.0/generate with an avatar_handle and a prompt, profile, or image input. Poll the job, then reuse the handle for avatar videos.

5 min readSume

All posts

To create a reusable AI avatar with Sume, send POST /v1/avatar-1.0/generate with an avatar_handle and an input built from a text prompt, structured profile traits, or a reference image. The request creates a job. When the job completes, you use the returned avatar handle or resource id to generate avatar videos.

Every API detail below comes from the Create new avatar docs page.

What are the three ways to create an avatar?

Every request carries a top-level avatar_handle plus an input union. Pick one of three inputs:

From Create new avatar, read 2026-09-25.
Way	Use it when	What goes in input
Prompt	You want to create an avatar from text only.	A description of the avatar you want.
Profile	Your app already has profile details for the avatar.	The `props` input type with structured traits. The docs example sends `ethnicity`, `sex`, and `age`.
Image	You have a reference image.	The `photo` input type with an `image_url`.

What does a create request look like?

This request creates an avatar from a reference image: the photo input type with a public image_url. The handle may include a leading @; Sume stores it normalized without @.

For the Profile way, swap the input for { "type": "props", "ethnicity": "Asian", "sex": "female", "age": 28 }, as in the docs example. The docs examples send an Idempotency-Key header, as this one does; see Idempotency keys for AI video APIs.

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"
    }
  }'

Which image URLs does avatar creation reject?

image_url must be a fetchable public HTTPS image URL (see Media inputs). Sume rejects these before generation submission:

Localhost URLs.
Private-network URLs.
Non-HTTPS URLs.
URLs whose response is not an image.

How do I know when the avatar is ready?

Poll the job, then fetch the result when its status is completed. Replace job_123 with your job's id.

curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

Which avatar routes should a new integration use?

Prefer the canonical Avatar 1.0 routes. The older paths remain supported and share the same request body.

From Create new avatar, read 2026-09-25.
Route	Role
`POST /v1/avatar-1.0/generate`	Canonical create route. Prefer it for new integrations.
`GET /v1/avatar-1.0/avatars`	Preferred resource route: list your avatars.
`GET /v1/avatar-1.0/avatars/avatar_123`	Preferred resource route: read one avatar.
`POST /v1/models/sume/avatar-1.0/generate/runs`	Canonical model-run alias.
`POST /v1/models/sume/avatar/v1.0/runs`	Legacy launch alias.
`GET /v1/avatars`, `GET /v1/avatars/:id`	Compatibility list and read routes. Response shape matches `/v1/avatar-1.0/avatars`.

How much does it cost to create an avatar?

API pricing lists avatar creation at $0.95 per avatar, and the default 5.5% agent fee applies on top. Videos you then generate with the avatar are priced per second by quality tier: $0.184/s standard, $0.245/s plus, $0.55/s max (no product image), also plus the agent fee.

What do I do with the avatar next?

Use the returned avatar handle on Generate avatar video; Talking avatar video API walks through a request. For first-frame review before a full render, start with Avatar video previews, covered in Avatar video previews: approve the first frame.

Sources

Written by Sume