HiAPI Video de Portavoz de Producto

¿Qué hace HiAPI Video de Portavoz de Producto?

Crea videos de producto de 3 a 15 segundos, de una sola toma, con la CLI local. Siempre estima con --dry-run antes de una solicitud paga. Crea una tarea paga solo cuando el usuario apruebe explícitamente la generación y el comando incluya --spend.

Enrutar el Escenario

Elige exactamente un escenario:

Escenario	Modelo	Entrada requerida	P0 por defecto
synthetic-spokesperson	kling-3.0-omni/text-to-video	Prompt y diálogo opcional	3s, 720p, 9:16, audio
talking-head	kling-3.0-omni/image-to-video	Una imagen de persona autorizada, prompt, diálogo, consentimiento	3s, 720p, audio
product-intro	seedance-2.0-fast	Prompt y 1-9 imágenes de producto	4s, 480p, 9:16, audio
brand-promo	seedance-2.0-fast	Prompt y 1-9 imágenes de marca o producto	4s, 480p, 9:16, audio

Antes de construir la solicitud, confirma la duración objetivo. Si el usuario no la especificó, pregunta cuántos segundos debe durar el video e indica el rango soportado: Kling 3-15 segundos; Seedance 4-15 segundos. Ofrece el P0 por defecto de la tabla, pero no procedas a --dry-run hasta que el usuario elija una duración o acepte explícitamente el valor por defecto.

Rechaza la generación talking-head a menos que el usuario confirme la autorización y el comando incluya --consent-confirmed. No inventes afirmaciones sobre el producto, avales, precios, certificaciones o hechos de la marca.

Proteger Gasto y Secretos

Ejecuta primero las verificaciones de costo cero:

node scripts/hiapi-product-spokesperson-video.mjs --check --env-file "R:\ruta\a\.env.local"

Luego ejecuta la solicitud prevista con --dry-run. Confirma que la estimación de precio público esté dentro del límite del usuario antes de reemplazar --dry-run con --spend. El límite de estimación del lado del cliente por defecto es $0.50; anúlalo solo dentro de un presupuesto explícitamente aprobado por el usuario. No crees más de una tarea paga por invocación.

Trata esto como una protección de estimación, no como un límite de cargo final impuesto por el servidor. HiAPI puede aplicar una relación de grupo específica de la cuenta durante el precargo de la tarea. Hasta que la API de tareas admita un campo de costo máximo del lado del servidor, divulga esta limitación antes de la generación paga y mantén un margen amplio por debajo del presupuesto total del usuario.

Lee HIAPI_API_KEY del entorno del proceso o de --env-file. Nunca imprimas, devuelvas, persistas ni incluyas la clave en vistas previas, artefactos, manifiestos, errores o registros. Usa almacenamiento temporal en P0.

Después de la instalación, copia .env.example a un archivo .env ignorado, o apunta --env-file a un archivo de entorno existente ignorado. Nunca confirmes el archivo con datos. Redacta tanto los datos de imagen incrustados como las URL de imágenes remotas de las vistas previas y los artefactos de solicitud guardados.

Ejecutar Localmente

Estima una solicitud de cabeza parlante autorizada sin gastar:

node scripts/hiapi-product-spokesperson-video.mjs `
  --scenario talking-head `
  --image-file "R:\media\persona-autorizada.jpg" `
  --prompt "Cámara fija, contacto visual natural, movimiento contenido" `
  --dialogue "Nuevo producto, ahora disponible." `
  --consent-confirmed `
  --env-file "R:\ruta\.env.local" `
  --max-cost-usd 0.50 `
  --dry-run

Para synthetic-spokesperson, omite la imagen y las opciones de consentimiento. Para escenarios de producto y marca, repite --reference-image-file o --reference-image-url. Los archivos JPEG, PNG y WebP locales se convierten a URIs de datos y no deben exceder 20 MiB cada uno.

Reanudar Sin Gastar de Nuevo

La CLI imprime la clave de idempotencia antes del envío y el ID de la tarea inmediatamente después de la creación. Si el envío se interrumpe antes de que se devuelva un ID de tarea, reintenta con la misma --idempotency-key. Si la encuesta se interrumpe después de la creación, ejecuta solo --task-id ID, --env-file y --output-dir deseado. Esto reanuda la encuesta y descarga el resultado existente sin reconstruir ni reenviar la solicitud original.

Preservar el Paquete de Salida

Escribe cada ejecución exitosa en outputs/ a menos que se proporcione --output-dir. Preserva:

• final.mp4;
• script.md y captions.srt;
• prompt.json con medios incrustados y URL de imágenes remotas redactadas;
• manifest.json con escenario, modelo, ID de tarea, estado, estimación, hash de solicitud, almacenamiento, marca de tiempo y vencimiento;
• qc.json marcado para revisión humana de voz, sincronización de labios, coherencia, continuidad y precisión de afirmaciones.

Nunca afirmes éxito sin una tarea final exitosa y un video local utilizable.

Manejar Fallos

• No reintentes HTTP 400, 401, 402 o 403.
• Reintenta el envío HTTP 409, 429 o 503 como máximo tres veces con la clave de idempotencia original.
• Reanuda las interrupciones de encuesta con --task-id; nunca envíes un reemplazo automáticamente.
• No regeneres después de un fallo de calidad sin aprobación explícita para otra ejecución paga.
• Informa el ID de la tarea, el estado final, la estimación, la ruta de salida local y las verificaciones de QC humano pendientes.