hiapi-product-spokesperson-video

HiAPI Product Spokesperson Video (Vídeo de Porta-Voz de Produto HiAPI)

Crie vídeos de produto de 3 a 15 segundos, em plano único, com a CLI local. Sempre estime com --dry-run antes de uma requisição paga. Crie uma tarefa paga apenas quando o usuário aprovar explicitamente a geração e o comando incluir --spend.

Roteie o Cenário

Escolha exatamente um cenário:

Cenário	Modelo	Entrada necessária	P0 padrão
synthetic-spokesperson	kling-3.0-omni/text-to-video	Prompt e diálogo opcional	3s, 720p, 9:16, áudio
talking-head	kling-3.0-omni/image-to-video	Uma imagem de pessoa autorizada, prompt, diálogo, consentimento	3s, 720p, áudio
product-intro	seedance-2.0-fast	Prompt e 1-9 imagens de produto	4s, 480p, 9:16, áudio
brand-promo	seedance-2.0-fast	Prompt e 1-9 imagens de marca ou produto	4s, 480p, 9:16, áudio

Antes de montar a requisição, confirme a duração alvo. Se o usuário não especificou, pergunte quantos segundos o vídeo deve ter e informe a faixa suportada: Kling 3-15 segundos; Seedance 4-15 segundos. Ofereça o padrão P0 da tabela, mas não prossiga para --dry-run até que o usuário escolha uma duração ou aceite explicitamente o padrão.

Recuse a geração de talking-head a menos que o usuário confirme a autorização e o comando inclua --consent-confirmed. Não invente alegações de produto, endossos, preços, certificações ou fatos de marca.

Proteja Gastos e Segredos

Execute as verificações de custo zero primeiro:

node scripts/hiapi-product-spokesperson-video.mjs --check --env-file "D:\caminho\.env.local"

Em seguida, execute a requisição pretendida com --dry-run. Confirme se a estimativa de preço público está dentro do limite do usuário antes de substituir --dry-run por --spend. O limite de estimativa padrão do lado do cliente é $0.50; sobrescreva-o apenas dentro de um orçamento explicitamente aprovado pelo usuário. Crie no máximo uma tarefa paga por invocação.

Trate isso como uma proteção de estimativa, não um limite de cobrança final imposto pelo servidor. A HiAPI pode aplicar uma taxa de grupo específica da conta durante o pré-carregamento da tarefa. Até que a API de tarefas suporte um campo de custo máximo no servidor, divulgue essa limitação antes da geração paga e mantenha uma margem substancial abaixo do orçamento total do usuário.

Leia HIAPI_API_KEY do ambiente do processo ou de --env-file. Nunca imprima, retorne, persista ou inclua a chave em prévias, artefatos, manifestos, erros ou logs. Use armazenamento temporário no P0.

Após a instalação, copie .env.example para um .env ignorado, ou aponte --env-file para um arquivo de ambiente ignorado existente. Nunca faça commit do arquivo preenchido. Redija tanto dados de imagem incorporados quanto URLs de imagem remotas de prévias e artefatos de requisição salvos.

Execute Localmente

Estime uma requisição autorizada de cabeça falante sem gastar:

node scripts/hiapi-product-spokesperson-video.mjs `
  --scenario talking-head `
  --image-file "D:\media\authorized-person.jpg" `
  --prompt "Câmera fixa, contato visual natural, movimento contido" `
  --dialogue "Novo produto, agora disponível." `
  --consent-confirmed `
  --env-file "D:\caminho\.env.local" `
  --max-cost-usd 0.50 `
  --dry-run

Para synthetic-spokesperson, omita a imagem e as opções de consentimento. Para cenários de produto e marca, repita --reference-image-file ou --reference-image-url. Arquivos JPEG, PNG e WebP locais são convertidos para data URIs e não devem exceder 20 MiB cada.

Retome Sem Gastar Novamente

A CLI imprime a chave de idempotência antes do envio e imprime o ID da tarefa imediatamente após a criação. Se o envio for interrompido antes que um ID de tarefa seja retornado, tente novamente com o mesmo --idempotency-key. Se a consulta for interrompida após a criação, execute apenas --task-id ID, --env-file e o --output-dir desejado. Isso retoma a consulta e baixa o resultado existente sem reconstruir ou reenviar a requisição original.

Preserve o Pacote de Saída

Escreva cada execução bem-sucedida em outputs/ a menos que --output-dir seja fornecido. Preserve:

• final.mp4;
• script.md e captions.srt;
• prompt.json com mídia incorporada e URLs de imagem remotas redigidas;
• manifest.json com cenário, modelo, ID da tarefa, status, estimativa, hash da requisição, armazenamento, timestamp e expiração;
• qc.json marcado para revisão humana de fala, sincronia labial, consistência, continuidade e precisão das alegações.

Nunca reivindique sucesso sem uma tarefa final bem-sucedida e um vídeo local utilizável.

Lidando com Falhas

• Não tente novamente HTTP 400, 401, 402 ou 403.
• Tente novamente envio HTTP 409, 429 ou 503 no máximo três vezes com a chave de idempotência original.
• Retome interrupções de consulta com --task-id; nunca envie um substituto automaticamente.
• Não regenere após uma falha de qualidade sem aprovação explícita para outra execução paga.
• Relate o ID da tarefa, status final, estimativa, caminho de saída local e verificações de QC humano pendentes.