Claude Code y la CLI de eroq: recursos desde un agente de código

Los agentes de código son buenos en todo lo que lleva una landing page, salvo en la imagen principal. Pueden escribir la etiqueta <picture>; no pueden producir la imagen. Las API de medios devuelven una URL o un blob en base64, y lo que un agente quiere de verdad es un archivo en una ruta que pueda referenciar en la siguiente edición. La CLI eroq cierra esa brecha: eroq mcp ejecuta un servidor MCP local por stdio cuyas herramientas guardan los renders como archivos en tu proyecto y devuelven la ruta.

Este es el flujo de trabajo que usamos nosotros mismos, con los comandos, las variables de entorno y una sesión completa al final.

Instala e inicia sesión

El paquete está en npm, necesita Node 18 o superior y no tiene ninguna dependencia.

npm install -g @eroq/cli
eroq login          # paste a key from the developers dashboard
eroq account        # balance, plan, workspace

eroq login guarda la clave en ~/.config/eroq/config.json con permisos 0600. Dos variables de entorno tienen prioridad sobre ella, que es lo que quieres en CI o en la configuración de un agente:

• EROQ_API_KEY: la clave; gana a la guardada.
• EROQ_API_URL: la URL base, por defecto https://eroq.ai. No la toques salvo que apuntes a un despliegue de staging.

Los comandos

Cada comando muestra lo que guardó y una línea de consumo («Spent 100 credits · 887 remaining», es decir, créditos gastados y restantes).

eroq models                                     # models, credit prices, plan gates
eroq voices                                     # roster + your clones
eroq enhance "kettle on a counter" --kind image # free prompt rewrite
eroq image "…" -m eroq-image-one -o public/img/hero.webp
eroq video "…" -s 10 --aspect 9:16 --shot push-in -o public/video/teaser.mp4
eroq speech "…" -v orion --speed 0.95 -o public/audio/intro.mp3

Opciones que vale la pena conocer: -m elige el modelo (las imágenes usan eroq-image-one por defecto y el video, eroq-motion-one), -s es la duración del clip en segundos (tu plan la limita y la tabla del motor la ajusta al valor válido más cercano; mira la documentación de video), --aspect acepta 16:9, 9:16 o 1:1, --shot es uno de los movimientos de cámara, --ref pasa la URL de una foto (imagen a video para los clips, una cara que mantener en las imágenes fijas), --negative es el prompt negativo y -o es la ruta de salida. Sin -o obtienes ./eroq-image-<timestamp>.webp, ./eroq-video-<timestamp>.mp4 o ./eroq-speech-<timestamp>.mp3.

Dos formas de conectarlo a Claude Code

Hay dos servidores, y se diferencian en algo importante.

Remoto, por HTTP. Claude Code habla directamente con https://eroq.ai/mcp. Las herramientas devuelven URL, y generate_video devuelve un id de trabajo cuando el render todavía no ha terminado.

claude mcp add --transport http eroq https://eroq.ai/mcp \
  --header "Authorization: Bearer eroq_sk_YOUR_KEY"

Local, por stdio. Claude Code lanza eroq mcp como proceso hijo. Las herramientas guardan archivos en el directorio de trabajo y devuelven la ruta; generate_video espera al render (hasta 8 minutos) para que el agente reciba un MP4, no un recibo.

claude mcp add eroq --env EROQ_API_KEY=eroq_sk_YOUR_KEY -- npx -y @eroq/cli mcp

Para trabajo de código, quédate con el local. eroq install claude-code imprime los dos fragmentos con tu clave guardada ya puesta. Las herramientas locales son generate_image, generate_video, generate_speech, enhance_prompt, list_models, list_voices, list_characters y get_account; las tres primeras aceptan un out_path.

Cursor lee ~/.cursor/mcp.json (o .cursor/mcp.json dentro de un proyecto):

{
  "mcpServers": {
    "eroq": {
      "url": "https://eroq.ai/mcp",
      "headers": { "Authorization": "Bearer eroq_sk_YOUR_KEY" }
    }
  }
}

Codex CLI lee ~/.codex/config.toml y ejecuta el servidor stdio:

[mcp_servers.eroq]
command = "npx"
args = ["-y", "@eroq/cli", "mcp"]
env = { EROQ_API_KEY = "eroq_sk_YOUR_KEY" }

eroq install cursor y eroq install codex también imprimen estos fragmentos. La matriz de conexión completa está en la documentación de MCP.

Una sesión realista: recursos para una landing page

La tarea: una landing page para una tetera de cuello de cisne ficticia, de las de café de filtro (los videos de producto son el caso clásico). El agente tiene el servidor local, una carpeta public/ y un presupuesto de unos 250 créditos. Esta es la traza, ligeramente recortada.

Agent: Checking the wallet before I spend anything.
       [get_account] → 1,000 credits, no plan (clips capped at 10 s)

Agent: Tightening the hero prompt first — it's free.
       [enhance_prompt kind=image prompt="black kettle, morning light, premium"]
       → "Close-up of a matte black pour-over kettle on a walnut counter, steam
          curling up into morning window light, shallow depth of field, soft cross
          lighting, a few coffee beans scattered out of focus, calm and premium,
          product photography, warm film palette."

Agent: [generate_image model=eroq-image-one out_path=public/img/hero.webp]
       → Image saved to public/img/hero.webp · Spent 10 credits · 990 remaining

Agent: Two feature tiles on the same look, then a vertical teaser.
       [generate_image … out_path=public/img/feature-pour.webp]   → 10 credits
       [generate_image … out_path=public/img/feature-temp.webp]   → 10 credits
       [generate_video model=eroq-motion-one seconds=10 aspect=9:16
        out_path=public/video/teaser.mp4
        prompt="Slow push-in on the same matte black kettle as steam rises and
        drifts toward the window, morning light warming from blue to gold, tiny
        dust motes in the beam, shallow focus holding on the spout, calm premium
        mood, 35mm film look."]
       → Clip saved to public/video/teaser.mp4 · Spent 60 credits · 910 remaining

Agent: A scratch voice-over for the hero, Orion, a touch slower.
       [generate_speech voice=orion speed=0.95 out_path=public/audio/intro.mp3
        text="Pour slower. Taste more. The kettle that waits for you."]
       → Speech saved to public/audio/intro.mp3 · Spent 3 credits · 907 remaining

Agent: Wiring them into index.html now.

Después escribe el marcado (<img src="/img/hero.webp">, un <video> silenciado en reproducción automática con el teaser, un elemento <audio> detrás de un botón de reproducción) y la página es real. Total: 93 créditos, unos dos dólares a la tarifa del paquete de entrada. Renderizar menos tomas que una persona es la única ventaja del agente aquí: no se enamora de la tercera variación.

Dos hábitos lo hacen fiable. Pide al agente que llame primero a get_account, para que conozca el límite de duración por clip del plan y el saldo antes de empezar. Y pasa siempre out_path: los nombres por defecto con marca de tiempo en la raíz del proyecto sirven para una prueba rápida y son un desastre en un repositorio.

Salvaguardas para un agente que puede gastar dinero

• Clave dedicada. Crea una para el agente, con sus propios límites de solicitudes, y revócala cuando termine el proyecto.
• Fuera de git. El --env de Claude Code y el TOML de Codex viven fuera del repositorio; un .cursor/mcp.json a nivel de proyecto con una clave dentro va en .gitignore.
• Los fallos son gratis. Un render que falla se reembolsa solo; un prompt fuera de la política devuelve content_blocked y nunca se cobra. El agente no necesita más lógica de reintento que «inténtalo una vez más y, si no, pregunta».
• Las restricciones de modelo son claras. Los motores de video premium necesitan un plan; un modelo bloqueado responde 403 plan_required antes de cualquier cobro. eroq models muestra qué puede usar tu clave.

Preguntas frecuentes

¿Necesito la CLI si ya uso el servidor MCP remoto?

No. El servidor remoto funciona con cualquier cliente que pueda enviar cabeceras. El servidor stdio de la CLI es para agentes que quieren archivos en disco en lugar de URL.

¿Qué modelos puede usar la CLI?

Todo lo que desbloquea tu plan: tres modelos de imagen, los motores de video que lista eroq models, los dos modelos de voz y el catálogo de voces, además de tus clones y tus personajes.

¿Puede el agente usar mis personajes?

Sí. list_characters devuelve tu reparto; generate_speech con char:<id> habla con la voz de ese personaje, y --ref con la foto de un personaje mantiene la cara de una imagen a otra o sirve de punto de partida para imagen a video.

¿Todo listo? Consigue una clave de API, ejecuta eroq login y deja que el agente haga la parte aburrida.