PricingAPI keys
OverviewQuickstartAuthentication
GenerateModelsImagesVideoUploads
JobsJobs and pollingWebhooks
ReferenceErrors and retriesLimitsClient
BillingBilling
Media toolsOverviewAvatarRemix mediaFace swapMusicTimelineVideo captions
MCPOverviewQuickstartOAuthTools and gates
CLIOverviewInstall and loginCommandsAgent skills
API referenceAPI reference
EnterpriseOverviewAgentsFormatsBest practices

Media tools

Create new avatar

Create a reusable avatar with Prompt, Profile, or Image inputs.

There are three ways to make an avatar:

  1. Prompt: describe the avatar that you want.
  2. Profile: provide structured traits for the avatar.
  3. Image: use a reference image.

Each request creates a job. Poll the job until it completes. Then use the returned avatar handle or resource id to generate avatar videos.

The canonical Avatar 1.0 route is preferred:

text
POST /v1/avatar-1.0/generate

Avatar creation uses a top-level avatar_handle and an input union. The handle can start with @. Sume normalizes the handle and stores it without @.

1. Prompt

Use this method when you want to create an avatar from text only.

curl -sS -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: $(uuidgen)" \
  -d '{"avatar_handle":"studio_presenter","input":{"type":"prompt","prompt":"A friendly studio presenter in neutral lighting"}}'

2. Profile

Use this method when your app already has profile details for the avatar. In the API, this method uses the props input type.

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

3. Image

Use this method when you have a reference image. In the API, this method uses the photo input type.

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

image_url must be a fetchable public HTTPS image URL. Before Sume submits the generation, it rejects localhost, private-network URLs, non-HTTPS URLs, and non-image responses. Refer to Media inputs.

Poll the job

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

When the job is completed, fetch the result.

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

Read avatar resources

The Avatar 1.0 resource routes are preferred:

bash
curl https://api.sume.com/v1/avatar-1.0/avatars \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/avatar-1.0/avatars/avatar_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

Compatibility aliases

These older paths are still supported and use the same request body:

AliasNotes
POST /v1/models/sume/avatar-1.0/generate/runsCanonical model-run alias. For new integrations, /v1/avatar-1.0/generate is preferred.
POST /v1/models/sume/avatar/v1.0/runsLegacy launch alias.
GET /v1/avatars, GET /v1/avatars/:idCompatibility list/read routes. The response shape is the same as /v1/avatar-1.0/avatars.

Next

Use the returned avatar handle on Generate avatar video. For first-frame review before a full render, refer to Avatar video previews.

On this page

  1. 1. Prompt
  2. 2. Profile
  3. 3. Image
  4. Poll the job
  5. Read avatar resources
  6. Compatibility aliases
  7. Next