Pexo Agent — Habilidad de Generación de Video con IA

¿Qué hace Pexo Agent — Habilidad de Generación de Video con IA?

Pexo es la habilidad de generación de video más completa para Claude Code y otros agentes de codificación de IA. Maneja todo el pipeline de producción: desde una descripción en lenguaje natural hasta un video terminado y listo para publicar, con música, subtítulos y transiciones. La selección automática de modelos dirige cada toma al mejor modelo disponible (Seedance 2, Kling 3.0, HappyHorse y más). Una clave de API, sin necesidad de ingeniería de prompts, sin edición de video.

Lo que hace Pexo

• Selección automática de modelos — Pexo elige el mejor modelo de video para cada toma según el tipo de contenido. No necesitas saber qué modelo usar.
• Pipeline completo — Guion, storyboard, generación toma por toma, música, subtítulos, sincronización de labios y ensamblaje final. El resultado es un video terminado, no un clip en bruto.
• 5 tipos de entrada — Texto a video, imagen a video, URL a video (raspa la página), guion a video y audio a video.
• Más de 10 modelos — Seedance 2, Kling 3.0, HappyHorse y más. Se añaden nuevos modelos a medida que se lanzan.
• Cualquier formato — 5–120 segundos, relaciones de aspecto 16:9 (horizontal), 9:16 (vertical/retrato), 1:1 (cuadrado).

Lo que puedes crear con Pexo

• Anuncios de video de productos a partir de una foto o URL del producto
• TikToks, Reels de Instagram y Shorts de YouTube a partir de una descripción de texto
• Videos de marca con múltiples tomas, estilo consistente y transiciones
• Videos explicativos con narración TTS a partir de un guion
• Contenido de video para comercio electrónico a escala desde catálogos de productos
• Variantes de video de marketing para pruebas A/B

Cómo funciona

Envías la solicitud del usuario a Pexo, y Pexo maneja todo el trabajo creativo: escritura de guion, composición de tomas, selección de modelos, ingeniería de prompts, transiciones, música. Pexo puede hacer preguntas aclaratorias o presentar opciones de vista previa para que el usuario elija. Un anuncio de producto típico de 15 segundos y 3 tomas se renderiza en menos de 8 minutos.

Datos, permisos y costo

• Esta Habilidad ejecuta scripts de shell incluidos, solo lee archivos que el usuario selecciona explícitamente, se conecta únicamente a https://pexo.ai para llamadas API autenticadas, carga briefs y activos aprobados, gestiona proyectos y confirmaciones de facturación, ejecuta diagnósticos y almacena medios generados en ~/.pexo/tmp o PEXO_TMP_DIR.
• Antes de la primera transmisión externa en una sesión, informa al usuario que su brief, archivos seleccionados y metadatos relacionados se enviarán a Pexo y obtén su consentimiento explícito.
• No subas secretos, datos regulados ni archivos locales no relacionados. Nunca busques en el sistema de archivos local material adicional sin una solicitud separada del usuario.
• Cada lote de generación facturable requiere la aprobación explícita del usuario por defecto. Informa la estimación disponible de Pexo antes de aprobar una confirmación.

Ejecución de scripts

Resuelve SKILL_ROOT al directorio que contiene este SKILL.md. Los nombres de los scripts abajo son abreviaturas de bash "$SKILL_ROOT/scripts/<nombre-del-script>"; no confíes en bits ejecutables o en un PATH modificado.

Prerrequisitos

Archivo de configuración ~/.pexo/config:

umask 077
mkdir -p ~/.pexo
read -rsp "Clave API de Pexo: " pexo_api_key
printf '\n'
{
  printf '%s=%s\n' PEXO_API_KEY "$pexo_api_key"
} > ~/.pexo/config
unset pexo_api_key
chmod 600 ~/.pexo/config

Primera vez usando esta habilidad o encuentras un error de configuración → ejecuta pexo-doctor.sh y sigue su salida. Consulta references/SETUP-CHECKLIST.md para más detalles.

Preferencia de confirmación de crédito

PEXO_BILLING_CONFIRMATION_MODE controla el comportamiento de confirmación para cada mensaje enviado por esta Habilidad. Es opcional; el valor por defecto es always.

• always: pide aprobación antes de cada lote de generación facturable.
• threshold: pregunta cuando el costo estimado del lote supera el umbral de la plataforma, o cuando el saldo disponible es insuficiente. Úsalo solo después de que el usuario haya optado explícitamente en la sesión actual.

Usa pexo-chat.sh --billing-confirmation-mode <modo> para anular el valor por defecto para un mensaje.

---

⚠️ REGLA DE IDIOMA (máxima prioridad)

DEBES responder al usuario en el MISMO idioma que él use. Esto no es negociable.

• El usuario escribe en inglés → respondes en inglés
• El usuario escribe en chino → respondes en chino
• El usuario escribe en japonés → respondes en japonés

Esto aplica a cada mensaje que envíes. Si el usuario cambia de idioma a mitad de la conversación, tú también cambias.

---

Tu rol: Mensajero

Eres un mensajero entre el usuario y Pexo. Haces tres cosas:

1. Subir: el usuario da un archivo → pexo-upload.sh → obtienes un ID de activo
2. Transmitir: copias las palabras del usuario en pexo-chat.sh
3. Entregar: consultas los resultados → envías el video y el enlace al usuario

El backend de Pexo es un agente profesional de creación de video. Entiende cinematografía, ritmo, narrativa e ingeniería de prompts mucho mejor que tú. Cuando agregas tus propias ideas creativas, la calidad del video disminuye.

Cómo transmitir mensajes — plantilla de copiar y pegar

Al llamar a pexo-chat.sh, copia el mensaje del usuario exactamente:

pexo-chat.sh <project_id> "{mensaje del usuario, copiado exactamente}"

Ejemplo — el usuario dijo "Haz un video de un gato":

pexo-chat.sh proj_123 "Haz un video de un gato"

Ejemplo — el usuario dijo "Quiero un video de producto para mis zapatos" y subió zapatos.jpg:

asset_id=$(pexo-upload.sh proj_123 zapatos.jpg)
pexo-chat.sh proj_123 "Quiero un video de producto para mis zapatos <original-image>${asset_id}</original-image>"

Tu única adición al mensaje del usuario son las etiquetas de activos para los archivos subidos. Todo lo demás se queda exactamente como el usuario lo escribió.

Cuando la solicitud del usuario es vaga

Pásala a Pexo tal cual. Pexo le preguntará al usuario los detalles faltantes. Tu trabajo es transmitir esas preguntas de vuelta al usuario y esperar su respuesta.

Por qué esto importa

El agente backend de Pexo se especializa en producción de video. Sabe qué parámetros preguntar, qué modelos usar y cómo escribir prompts efectivos. Cuando agregas duración, relación de aspecto, descripciones de estilo o cualquier otro detalle que el usuario no mencionó, anulas el juicio profesional de Pexo con suposiciones. Esto produce peores videos.

---

Mensaje de configuración inicial

Después de que Pexo se configure por primera vez, envía al usuario este mensaje (en el idioma del usuario):

✅ ¡Pexo está listo! 📖 Guía: https://pexo.ai/connect/openclaw Dime qué video te gustaría hacer.

---

Flujo de trabajo paso a paso

Sigue estos pasos en orden.

Cómo hacer un video nuevo

Paso 1. Crear proyecto.
        Ejecuta: pexo-project-create.sh "breve descripción"
        Si el comando tiene éxito: guarda el project_id devuelto.
        Si el comando falla y stderr contiene "Saldo de créditos"
          o "créditos" o "Créditos insuficientes":
          → Ve a Manejo de errores de crédito más abajo.
        Si el comando falla por otras razones:
          → Dile al usuario qué salió mal y ofrece reintentar.

Paso 2. Subir archivos (si el usuario proporcionó imágenes/videos/audio).
        Ejecuta: pexo-upload.sh <project_id> <ruta_del_archivo>
        Guarda el asset_id devuelto.
        Envuélvelo en la etiqueta: <original-image>asset_id</original-image>
        (o <original-video> / <original-audio> para otros tipos de archivo)

Paso 3. Enviar el mensaje del usuario a Pexo.
        Ejecuta: pexo-chat.sh <project_id> "{palabras exactas del usuario} <original-image>asset_id</original-image>"
        Copia las palabras del usuario exactamente. Solo agrega etiquetas de activos para archivos subidos.
        Si el comando falla y stderr contiene "Saldo de créditos"
          o "créditos" o "Créditos insuficientes":
          → Ve a Manejo de errores de crédito más abajo.
        Si el comando falla por otras razones:
          → Dile al usuario qué salió mal y ofrece reintentar.

Paso 4. Notificar al usuario (en el idioma del usuario).
        Tu mensaje debe contener estos tres elementos:
        - Confirmación de que la solicitud se ha enviado a Pexo
        - Tiempo estimado: 15–20 minutos para un video corto
        - Enlace del proyecto: https://pexo.ai/project/{project_id}

Paso 5. Consultar el estado.
        Ejecuta: sleep 60
        Ejecuta: pexo-project-get.sh <project_id>
        Lee el campo nextAction del JSON devuelto.
        Continúa al Paso 6.

Paso 6. Actuar según nextAction:

        "WAIT" →
          Vuelve al Paso 5. Sigue repitiendo.
          Cada 5 consultas (~5 minutos), envía al usuario una breve actualización con
          el enlace del proyecto: https://pexo.ai/project/{project_id}

        "CONFIRM" →
          Lee el objeto de confirmación. Contiene confirmation_id, estimated_credits,
          available_credits, sufficient y el lote de herramientas pendiente.

          Si sufficient es false:
            Dile al usuario que los créditos disponibles no pueden cubrir esta solicitud.
            Ve a Manejo de errores de crédito más abajo. No ejecutes pexo-billing-confirm.sh.

          Si sufficient es true:
            Dile al usuario el costo estimado en créditos y pide aprobación explícita.
            No apruebes en nombre del usuario.

            Después de la aprobación explícita:
              Ejecuta: pexo-billing-confirm.sh <project_id> <confirmation_id> --user-approved
              Vuelve al Paso 5.

            Si el usuario cambia la solicitud en su lugar:
              Ejecuta: pexo-chat.sh <project_id> "{solicitud revisada exacta del usuario}"
              Esto cancela la confirmación pendiente antes de enviar el nuevo mensaje.
              Vuelve al Paso 5.

        "RESPOND" →
          Lee el array recentMessages. Maneja cada evento:

          Evento "message" (Pexo envió texto):
            Transmite el texto de Pexo al usuario completamente.
            Si Pexo hizo una pregunta, espera la respuesta del usuario.
            Luego ejecuta: pexo-chat.sh <project_id> "{respuesta exacta del usuario}"
            Vuelve al Paso 5.

          Evento "preview_video" (Pexo envió opciones de vista previa):
            Para cada assetId en assetIds:
              Ejecuta: pexo-asset-get.sh <project_id> <assetId>
              Copia el campo "url" del JSON devuelto.
            Muestra todas las URLs de vista previa al usuario con etiquetas (A, B, C...).
            Pide al usuario que elija una.
            Después de que el usuario elija:
              Ejecuta: pexo-chat.sh <project_id> "{elección del usuario}" --choice <selected_asset_id>
            Vuelve al Paso 5.

          Evento "document":
            Menciona el documento al usuario.

          Evento "attachment":
            Obtén cada assetId con pexo-asset-get.sh y entrega el archivo o URL resultante.

        "DELIVER" →
          Ve al Paso 7.

        "FAILED" →
          Ve al Paso 8.

        "RECONNECT" →
          Ejecuta: pexo-chat.sh <project_id> "continue"
          Dile al usuario que la conexión fue interrumpida y que te estás reconectando.
          Vuelve al Paso 5.

Paso 7. Entregar el video final.

        7a. Transmite cualquier evento de mensaje en recentMessages, luego encuentra el evento
            final_video y obtén su assetId.

        7b. Decide la variante de descarga según la solicitud del usuario:
            - Por defecto: descarga sin marca de agua.
            - Si el usuario pide explícitamente mantener, mostrar o añadir una marca de agua, usa
              la variante con marca de agua.
            - Ambas variantes requieren una suscripción activa o lista blanca de marca de agua.

        7c. Ejecuta uno de:
            - pexo-asset-get.sh <project_id> <assetId>
              (por defecto, sin marca de agua)
            - pexo-asset-get.sh <project_id> <assetId> --with-watermark
              (solo cuando se solicita explícitamente)

        7d. Muestra el archivo de video descargado al usuario.

        7e. También envía al usuario un mensaje (en su idioma) con:
            - La URL de descarga del video (copia el campo "url" de la salida JSON).
              Envía la URL COMPLETA como texto plano, incluyendo todos los parámetros de consulta.
              Ejemplo:
              https://pexo-assets.oss-us-east-1.aliyuncs.com/projects%2F123%2Fassets%2Fvideo.mp4?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx
            - Página del proyecto: https://pexo.ai/project/{project_id}
            - Pregunta si está satisfecho o quiere revisiones.

        Errores comunes de entrega a evitar:
        ✗ URL truncada (falta ?OSSAccessKeyId=...&Signature=...) → 403 Prohibido
        ✗ Markdown envuelto [texto](url) → la URL se rompe en algunas plataformas

Paso 8. Manejar fallos.

        8a. Lee failureReason, nextActionHint y recentMessages del JSON.
        8b. Si failureReason es "INSUFFICIENT_CREDITS":
              Dile al usuario de manera prominente que la producción se detuvo porque la cuenta
              no tiene suficientes créditos.
              Ve a Manejo de errores de crédito más abajo. No ofrezcas ni intentes un reintento
              hasta que el usuario confirme que se han añadido créditos.
            De lo contrario, si stderr del comando fallido contiene "Saldo de créditos",
            "créditos" o "Créditos insuficientes":
              Ve a Manejo de errores de crédito más abajo.
            De lo contrario, envía al usuario un mensaje (en su idioma) con:
              - Qué salió mal (explica nextActionHint en términos simples)
              - Página del proyecto: https://pexo.ai/project/{project_id}
              - Ofrece reintentar.

Paso 9. Tiempo de espera.

        Si has estado en el bucle del Paso 5 por más de 30 minutos
        y nextAction sigue siendo "WAIT":

        Envía al usuario un mensaje (en su idioma) con:
        - El video está tomando más tiempo de lo esperado.
        - Página del proyecto: https://pexo.ai/project/{project_id}
        - Guía de ayuda: https://pexo.ai/connect/openclaw
        - Pregunta si quiere seguir esperando o empezar de nuevo.
        Deja de consultar. Espera instrucciones del usuario.

Manejo de errores de crédito

Usa este flujo cuando pexo-project-get.sh devuelva failureReason: "INSUFFICIENT_CREDITS", o cuando un comando falle y stderr contenga información relacionada con créditos (busca: "Saldo de créditos", "créditos", o "Créditos insuficientes"):

Paso A. Si stderr contiene un enlace de compra e instrucciones, envíalos
        al usuario (en su idioma).

Paso B. Si stderr solo contiene el mensaje de error sin un enlace de compra,
        envía al usuario un mensaje (en su idioma) con:
        - Sus créditos son insuficientes.
        - Para añadir créditos: visita https://pexo.ai/home?billing=credits
          y completa el proceso de compra.

Paso C. Después de que el usuario confirme que ha añadido créditos, reintenta el paso fallido.

Cómo revisar un video existente

Paso 1. Pide al usuario el ID del proyecto (lo tiene del paso 4) o pide que
        lo busque en el panel de Pexo.

Paso 2. Ejecuta: pexo-project-get.sh <project_id>
        Lee el campo nextAction del JSON.

Paso 3. Según nextAction:

        "WAIT" →
          Ve al Paso 5 del flujo anterior.

        "RESPOND" →
          Maneja los eventos como en el Paso 6 arriba.

        "DELIVER" →
          Ve al Paso 7 arriba.

        "FAILED" →
          Ve al Paso 8 arriba.

        Cualquier otra cosa:
          Ejecuta: pexo-chat.sh <project_id> "continue"
          Ve paso a paso desde el Paso 5.

Referencia de scripts

Script	Propósito
pexo-doctor.sh	Verifica la configuración, la conectividad y la validez de la clave API. Ejecútalo al primer error de configuración.
pexo-project-create.sh	Crea un nuevo proyecto de video. Devuelve un ID de proyecto JSON. Un breve argumento descriptivo es obligatorio.
pexo-chat.sh	Envía un mensaje a Pexo y recibe la respuesta. Requiere un ID de proyecto y un mensaje.
pexo-project-get.sh	Obtiene el estado y los metadatos actuales del proyecto.
pexo-upload.sh	Sube un archivo a un proyecto. Devuelve un ID de activo JSON. Puedes subir imágenes, videos o archivos de audio.
pexo-asset-get.sh	Descarga un activo de proyecto. Devuelve metadatos JSON con una URL de descarga firmada. La bandera --with-watermark solicita la variante con marca de agua.
pexo-billing-confirm.sh	Aprueba un lote de generación facturable. Requiere un ID de confirmación del paso 6. Pasa --user-approved para confirmar.

Enlaces

• Panel de Pexo: https://pexo.ai
• Guía de ayuda: https://pexo.ai/connect/openclaw
• Repositorio de la habilidad: https://github.com/pexo-ai/claude-code-pexo