Avatares

Avatar = um personagem com identidade preservada (rosto, cabelo, corpo) que entra como referência de identidade nos jobs UGC — avatar_ids nos params do ugc_job_create. Um avatar tem uma imagem base (a identidade principal), uma pasta de imagens (referências extras) e folhas versionadas de ângulos/expressões.

Ciclo de vidaCopiar link da âncora

• creating → ready | failed — avatar criado por job fica creating até o job terminar (poll via ugc_job_get com o jobId devolvido). Falha → failed + estorno.
• Upload asis nasce ready na hora — grátis.

Criar avatarCopiar link da âncora

De uma imagem — ugc_avatar_create_uploadCopiar link da âncora

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

• asis (default): a foto vira a base imediatamente — grátis, sem job.
• recreate: job i2i regenera a base limpa a partir da foto — debita créditos; model_key/aspect_ratio opcionais. A foto original também entra na pasta como referência.

Gerado por IA — ugc_avatar_create_generatedCopiar link da âncora

{
  "name": "Maria",
  "characteristics": { "gender": "Female", "ageRange": "25-34", "...": "..." },
  "free_prompt": "direção extra opcional",
  "model_key": "opcional", "aspect_ratio": "9:16 (default)"
}

characteristics vem do catálogo — leia ugc_avatar_options (campos, valores e quais aparecem por gender) ou use ugc_avatar_randomize para uma combinação válida pronta. Debita créditos (job avatar_base).

Ler e gerenciarCopiar link da âncora

ugc_avatars_list / ugc_avatar_getCopiar link da âncora

{ "q": "busca por nome (opcional)" }        // list
{ "avatar_id": "..." }                      // get

O detalhe traz images (a pasta — com qual é a base) e sheets (folhas, com isCurrent — só a vigente entra como ref).

ugc_avatar_update / ugc_avatar_deleteCopiar link da âncora

Renomeia / remove (soft delete — mídias e jobs sobrevivem).

Pasta de imagensCopiar link da âncora

Referências extras do avatar (variações de look, ângulos caseiros):

ugc_avatar_image_addCopiar link da âncora

{ "avatar_id": "...", "media_id": "file_id", "label": "look praia (opcional)" }

Grátis — adiciona à pasta sem virar base.

ugc_avatar_image_set_baseCopiar link da âncora

{ "avatar_id": "...", "image_id": "id da linha da pasta (images_list)" }

Promove uma imagem da pasta a base — grátis. A base é a identidade principal usada como ref nos jobs.

ugc_avatar_image_deleteCopiar link da âncora

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

Remove da pasta (o media_file sobrevive). Se era a base, outra é promovida — ou indique new_base_image_id. A última imagem não sai (avatar sem referência é inválido).

Folhas de referência (sheets)Copiar link da âncora

Folha = grid gerado por IA com variações do avatar — angles (ângulos de rosto/corpo) ou expressions (expressões faciais). Melhora muito a consistência da identidade nos jobs.

ugc_avatar_sheet_generateCopiar link da âncora

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

Debita créditos — job i2i apoiado na base + folhas ativas. Cada chamada cria a próxima version; a succeeded mais alta vira a vigente (isCurrent: true) e só ela entra como ref. Acompanhe com ugc_job_get.

ugc_avatar_sheets_listCopiar link da âncora

→ todas as versões com status e isCurrent.

Usando o avatar em jobsCopiar link da âncora

{
  "model_key": "...",
  "prompt": "@maria num café em Paris",
  "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 desliga a base como ref.
• avatar_sheet_kinds limita quais folhas vigentes entram (omitido = todas).
• Recriar cena (pose_copy, default ligado): adicione extra_ref_media_ids com a foto de referência — o job recria pose, enquadramento, roupa e cenário com o avatar no lugar da pessoa:

{
  "params": {
    "avatar_ids": ["avatar_id"],
    "extra_ref_media_ids": ["file_id da foto de referência"],
    "pose_copy": true
  }
}

Ver também: UGC — Geração · Geração de vídeo