Avatars

An avatar is a character with preserved identity (face, hair, body) that enters jobs as an identity reference — avatar_ids in ugc_job_create params. An avatar has a base image (the main identity), an image folder (extra references) and versioned angle/expression sheets.

LifecycleCopy Anchor Link

• creating → ready | failed — an avatar created by a job stays creating until the job finishes (poll via ugc_job_get with the returned jobId). Failure → failed + refund.
• asis upload becomes ready immediately — free.

Creating avatarsCopy Anchor Link

From an image — ugc_avatar_create_uploadCopy Anchor Link

{
  "name": "Maria",
  "media_id": "file_id (media_upload_from_url or storage_*)",
  "mode": "asis"
}

• asis (default): the photo becomes the base immediately — free, no job.
• recreate: an i2i job regenerates a clean base from the photo — debits credits; optional model_key/aspect_ratio. The original photo also joins the folder as a reference.

AI-generated — ugc_avatar_create_generatedCopy Anchor Link

{
  "name": "Maria",
  "characteristics": { "gender": "Female", "ageRange": "25-34", "...": "..." },
  "free_prompt": "optional extra direction",
  "model_key": "optional", "aspect_ratio": "9:16 (default)"
}

characteristics comes from the catalog — read ugc_avatar_options (fields, values and which appear per gender) or use ugc_avatar_randomize for a valid ready-made combination. Debits credits (avatar_base job).

Reading & managingCopy Anchor Link

ugc_avatars_list / ugc_avatar_getCopy Anchor Link

{ "q": "name search (optional)" }           // list
{ "avatar_id": "..." }                      // get

The detail returns images (the folder — with which one is the base) and sheets (with isCurrent — only the current one enters as a ref).

ugc_avatar_update / ugc_avatar_deleteCopy Anchor Link

Rename / remove (soft delete — media and jobs survive).

Image folderCopy Anchor Link

Extra references for the avatar (look variations, homemade angles):

ugc_avatar_image_addCopy Anchor Link

{ "avatar_id": "...", "media_id": "file_id", "label": "beach look (optional)" }

Free — adds to the folder without becoming the base.

ugc_avatar_image_set_baseCopy Anchor Link

{ "avatar_id": "...", "image_id": "folder row id (images_list)" }

Promotes a folder image to base — free. The base is the main identity used as a ref in jobs.

ugc_avatar_image_deleteCopy Anchor Link

{ "avatar_id": "...", "image_id": "...", "new_base_image_id": "optional" }

Removes from the folder (the media_file survives). If it was the base, another is promoted — or pass new_base_image_id. The last image can't be removed (an avatar without references is invalid).

Reference sheetsCopy Anchor Link

A sheet is an AI-generated grid of avatar variations — angles (face/body angles) or expressions (facial expressions). Greatly improves identity consistency in jobs.

ugc_avatar_sheet_generateCopy Anchor Link

{ "avatar_id": "...", "kind": "angles|expressions", "model_key": "optional" }

Debits credits — an i2i job built on the base + active sheets. Each call creates the next version; the highest succeeded becomes current (isCurrent: true) and only it enters as a ref. Track with ugc_job_get.

ugc_avatar_sheets_listCopy Anchor Link

→ all versions with status and isCurrent.

Using the avatar in jobsCopy Anchor Link

{
  "model_key": "...",
  "prompt": "@maria in a Paris café",
  "params": {
    "avatar_ids": ["avatar_id"],
    "avatar_include_base": true,
    "avatar_sheet_kinds": ["angles", "expressions"],
    "mentions": [{ "token": "@maria", "kind": "avatar", "id": "avatar_id" }]
  }
}

• avatar_include_base: false disables the base as a ref.
• avatar_sheet_kinds limits which current sheets enter (omitted = all).
• Scene recreate (pose_copy, default on): add extra_ref_media_ids with the reference photo — the job recreates pose, framing, outfit and setting with the avatar replacing the person:

{
  "params": {
    "avatar_ids": ["avatar_id"],
    "extra_ref_media_ids": ["file_id of the reference photo"],
    "pose_copy": true
  }
}

See also: UGC — Generation · Video generation