Create a Sume avatar from a photo: what image_url must satisfy

Send input.type: "photo" with a fetchable public HTTPS image_url to POST /v1/avatar-1.0/generate. Before Sume submits the generation it rejects localhost, private-network and non-HTTPS URLs, and any response that is not an image. A signed or login-gated link will not work, so host the photo where an anonymous request can read it.

Three ways in, one route

Avatar creation uses a top-level avatar_handle and an input union. The handle may start with @, and Sume normalises it and stores it without the @. The union has three forms: prompt for text only, props for structured traits, and photo for a reference image.

Each request creates a job, not an avatar. Poll the job until it completes, then use the returned handle or resource id on 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"
    }
  }'

What the URL check rejects

The same fetchability rule applies to every media field in the Avatar family, including product_image, scene.image_url and the background images in video_inputs. The shared guide is Media inputs.

Choosing photo, props or prompt

Whichever you choose, keep the handle stable. Every later call refers to the avatar by avatar_handle, and a reserved prefix is refused, so pick a name that belongs to your own series.

• Use photo when a real reference image exists and you want the avatar to follow it.
• Use props when your app already stores traits and you want repeatable, structured creation.
• Use prompt when you only have a description.

Before you upload a face

A reference photo of a real person is a decision about consent, not just about format. Confirm that the person agreed to the use before you send the image, and keep the record with the handle. Sume validates the URL; it cannot validate the permission.

After the avatar is ready, read it with GET /v1/avatar-1.0/avatars/{id}, then make a preview of the first video before the full render.

Older paths

POST /v1/models/sume/avatar-1.0/generate/runs and the legacy POST /v1/models/sume/avatar/v1.0/runs accept the same body. For new integrations the docs prefer /v1/avatar-1.0/generate.