Geração de imagem/vídeo/áudio com IA via MCP — fluxo completo (mídia → modelo → estimativa → job → poll), cenários e custo em créditos.
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.
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.ugc_models_list devolve model_key + capabilities
(aspectRatios, resolutions, durationsSec, acceptsImageRefs,
acceptsDrivingVideo, lipsync) + hint de preço.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.credits_balance confere se o usuário tem créditos.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).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.failed estorna automaticamente;
ugc_job_cancel cancela e devolve os créditos integralmente.ugc_models_list{ "output_kind": "image|video|audio (opcional — filtra)" }→ { "models": [{ "key", "displayName", "outputKind", "brand", "capabilities", "estimatedCreditsPerUnit" }] }
ugc_estimate{
"model_key": "seedance-2.0",
"prompt": "opcional quando há refs",
"params": { "...": "mesmo schema do ugc_job_create" }
}→ { "credits", "mode", "provider", "fallbackProvider" }
credits é o número que o ugc_job_create cobra com o mesmo input. Imagem,
vídeo e voz descontam primeiro dos créditos do plano, até o limite de mídia
(media_cap); o resto sai dos créditos avulsos.
ugc_job_create{
"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_get{ "job_id": "..." }→ status (queued|running|succeeded|failed|cancelled), costCredits,
charged, refunded, resultMediaId, resultUrl. Job failed volta com
errorReason: null e refunded: true: os créditos voltam. Tente de novo ou
troque as opções (ugc_estimate confere antes). Poll manual — repita até
o status terminal.
ugc_jobs_list{
"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_deleteCancela job não-terminal com estorno integral / remove da galeria (job ativo é cancelado antes — o media_file sobrevive).
{ "job_id": "..." }Cenários são fundos reutilizáveis — scene_id nos params de job aplica o
cenário como fundo.
ugc_scene_create — três caminhos{ "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_deleteLista (cena com jobId + url: null ainda está gerando), renomeia e remove
(soft delete).
media_upload_from_url{ "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_listTemplates = vídeos de driving ingeridos (use o id como template_id em
vídeo). Projetos = organização dos jobs (project_id).
credits_balance→ { "monthly_balance", "topup_balance", "total_balance", "monthly_allowance", "cycle_started_at", "cycle_ends_at", "plan_name", "member_limit", "scope", "media_cap", "media_used" }
monthly_balance — os créditos do plano. Renovam a cada ciclo.topup_balance — os créditos avulsos. Não vencem.media_cap / media_used — quanto dos créditos do plano pode ir para
imagem, vídeo e voz no ciclo, e quanto já foi. null = sem limite. No
Pro o limite é 3.000 créditos; no Max, 8.000. Passou do limite, a mídia
sai dos créditos avulsos, que não têm limite de mídia.member_limit — { "limit", "used", "resets_at" } quando o usuário tem
um limite próprio no workspace. Com scope: "member" os saldos são o que
sobra desse limite.Consulte antes de qualquer operação que debita. Quando o débito não passa,
a tool volta isError com a mensagem do erro. Na API REST, o mesmo erro
chega com um destes códigos:
| Código | HTTP | Quando |
|---|---|---|
INSUFFICIENT_CREDITS | 402 | O saldo do workspace não cobre a operação. Créditos avulsos resolvem. |
MEMBER_CREDIT_LIMIT | 402 | O usuário passou do próprio limite no ciclo. Comprar crédito não resolve: só o dono sobe o limite, ou a janela zera (can_top_up: false). |
MEDIA_CAP_REACHED | 402 | A mídia usou o limite do plano no ciclo e não há créditos avulsos para cobrir. Créditos avulsos resolvem (can_top_up: true). |
TOPUP_BELOW_MINIMUM | 400 | O valor da compra de créditos avulsos fica abaixo do mínimo: R$ 10 no Pix, R$ 20 no cartão. |
TOPUP_UNAVAILABLE | 400 | O workspace não pode comprar créditos avulsos (sem assinatura ativa). |
Ver também: Avatares · Geração de vídeo · Tools