PricingAPI keys
  • Overview
  • Quickstart
  • Authentication
  • Overview
  • Audio detach
  • Create new avatar
  • Avatar video previews
  • Generate avatar video
  • Face swap (Beta)
  • Music 1.0
  • Music Router
  • Reference ingest
  • Remix media
  • Timeline 1.0
  • Timeline audio
  • Timeline compose
  • Trending videos
  • Video analyses
  • Video captions
  • Video filter
  • Video frames
  • Video inspect
  • Video trim

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.dev.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. Prompt
  • 2. Profile
  • 3. Image
  • Poll the job
  • Read avatar resources
  • Compatibility aliases
  • Next