UGC — Geração

O namespace ugc_* expõe o motor de geração de conteúdo do uPubly: modelos de imagem, vídeo e áudio roteados por leilão de providers, com débito em créditos e estorno automático em falha/cancelamento.

Fluxo completo de uma geraçãoCopiar link da âncora

1. Mídia de entrada (opcional) — traga imagens de referência: media_upload_from_url (URL → file_id numa chamada, só URLs públicas, máx 20MB) ou o caminho presignado em 2 passos (storage_request_upload → PUT → storage_complete_upload). O file_id devolvido é o media_id usado em refs, avatares e cenários.
2. Modelo — ugc_models_list devolve model_key + capabilities (aspectRatios, resolutions, durationsSec, acceptsImageRefs, acceptsDrivingVideo, lipsync) + hint de preço.
3. Estimativa — ugc_estimate com o mesmo input do create: roda o mesmo roteamento/leilão sem gravar nem debitar. O número exibido é o número cobrado.
4. Saldo — credits_balance confere se o usuário tem créditos.
5. Job — ugc_job_create DEBITA CRÉDITOS na criação e devolve o job queued. Envie idempotency_key para retry seguro (sem ela o backend deriva uma do payload — retry nunca cobra 2x).
6. Poll — o job é assíncrono: ugc_job_get até succeeded ou failed. O resultado chega em resultUrl / resultMediaId — que é um file_id reutilizável como referência em jobs seguintes.
7. Falha/cancelamento — failed estorna automaticamente; ugc_job_cancel cancela e devolve os créditos integralmente.

Catálogo & custoCopiar link da âncora

ugc_models_listCopiar link da âncora

{ "output_kind": "image|video|audio (opcional — filtra)" }

→ { "models": [{ "key", "displayName", "outputKind", "brand", "capabilities", "estimatedCreditsPerUnit" }] }

ugc_estimateCopiar link da âncora

{
  "model_key": "seedance-2.0",
  "prompt": "opcional quando há refs",
  "params": { "...": "mesmo schema do ugc_job_create" }
}

→ { "credits", "usdEstimated", "mode", "provider", "fallbackProvider" }

JobsCopiar link da âncora

ugc_job_createCopiar link da âncora

{
  "model_key": "obrigatório (ugc_models_list)",
  "prompt": "opcional quando há refs suficientes",
  "idempotency_key": "recomendado",
  "params": {
    "duration_sec": 5,
    "aspect_ratio": "9:16|16:9|1:1",
    "resolution": "720p|1080p",
    "image_ref_media_ids": ["media_id — ref visual direta (i2i)"],
    "extra_ref_media_ids": ["media_id — cena/estilo; com avatar+pose_copy vira a cena copiada"],
    "driving_video_media_id": "media_id do vídeo de driving (motion/lipsync)",
    "avatar_ids": ["avatar_id — identidade entra como ref (base+folhas)"],
    "avatar_include_base": true,
    "avatar_sheet_kinds": ["angles", "expressions"],
    "pose_copy": true,
    "voice_id": "voz (áudio/lipsync)",
    "timestamps": true,
    "format": "mp4",
    "scene_id": "cenário da biblioteca como fundo",
    "template_id": "driving template (ugc_templates_list)",
    "project_id": "projeto p/ organizar (ugc_projects_list)",
    "script_id": "roteiro vinculado",
    "mentions": [{ "token": "@maria", "kind": "avatar|scene|ref", "id": "..." }],
    "extra": { "params específicos do provider": "..." }
  }
}

→ { "job": { "id", "status", "costCredits", "charged", "params", ... }, "replayed": false }

avatar_ids trazem as refs de identidade do avatar (base + folhas vigentes — controle fino via avatar_include_base / avatar_sheet_kinds). extra_ref_media_ids com pose_copy: true (default quando há avatar+extras) ativam o modo recriar cena: a imagem extra define pose, enquadramento e cenário, e o avatar substitui a pessoa. Com pose_copy: false as extras são só contexto de estilo.

ugc_job_getCopiar link da âncora

{ "job_id": "..." }

→ status (queued|running|succeeded|failed|cancelled), costCredits, charged, refunded, errorReason, resultMediaId, resultUrl. Poll manual — repita até o status terminal.

ugc_jobs_listCopiar link da âncora

{
  "kind": "image|video|audio", "status": "...", "avatar_id": "?",
  "project_id": "?", "page": 0, "size": 20, "ready_for_video": true
}

→ galeria do workspace (mais recentes primeiro).

ugc_job_cancel / ugc_job_deleteCopiar link da âncora

Cancela job não-terminal com estorno integral / remove da galeria (job ativo é cancelado antes — o media_file sobrevive).

{ "job_id": "..." }

CenáriosCopiar link da âncora

Cenários são fundos reutilizáveis — scene_id nos params de job aplica o cenário como fundo.

ugc_scene_create — três caminhosCopiar link da âncora

{ "name": "Estúdio neon", "media_id": "file_id" }

→ Upload direto — a imagem vira o cenário. Grátis, sem job.

{ "name": "Praia vazia", "prompt": "praia ao entardecer", "model_key": "...", "aspect_ratio": "9:16" }

→ t2i de ambiente vazio (o backend instrui "sem pessoas" automaticamente). Job purpose=scene — devolve job_id p/ poll.

{ "name": "Copiar café", "ref_media_ids": ["file_id"], "prompt": "direção extra opcional" }

→ Copiar cenário (i2i): recria localização, enquadramento, luz e mood das refs removendo pessoas. Refs sozinhas já bastam — prompt é só direção extra.

ugc_scenes_list / ugc_scene_update / ugc_scene_deleteCopiar link da âncora

Lista (cena com jobId + url: null ainda está gerando), renomeia e remove (soft delete).

AuxiliaresCopiar link da âncora

media_upload_from_urlCopiar link da âncora

{ "url": "https://.../imagem.png", "file_name": "opcional" }

→ { "file_id", "file_url" } numa chamada. Só URLs públicas http(s) — IPs privados/loopback/link-local são rejeitados (anti-SSRF), máx 20MB.

ugc_templates_list / ugc_projects_listCopiar link da âncora

Templates = vídeos de driving ingeridos (use o id como template_id em vídeo). Projetos = organização dos jobs (project_id).

SaldoCopiar link da âncora

credits_balanceCopiar link da âncora

→ { "monthly_balance", "topup_balance", "total_balance", "monthly_allowance", "cycle_ends_at", "plan_name" }

Consulte antes de qualquer operação que debita — crédito insuficiente volta isError com a mensagem de saldo.

Ver também: Avatares · Geração de vídeo · Tools