Picmovi Photo to Video MCP

PicMovi Photo to Video MCP

Herramientas de agente de código abierto para PicMovi, una plataforma de foto a video: convierte fotos fijas en clips cortos, o crea videos a partir de fotos con un último fotograma opcional.

Este repositorio incluye un cliente REST tipado, una CLI y un adaptador MCP stdio local. Identidad en vivo, créditos, cotizaciones, fotos propias, concurrencia de plan y trabajos de video son servidos por PicMovi Agent REST (/api/agent/v1/*). El MCP HTTP Streamable alojado (/api/mcp + OAuth) es la ruta MCP remota posterior.

Qué pueden hacer los agentes

Los agentes conectados pueden:

1. Descubrir modelos de foto a video (models_list)
2. Consultar créditos disponibles (credits_get)
3. Cotizar un trabajo de foto a video (generation_quote) — sin cargo
4. Después de la aprobación explícita de créditos, iniciar un trabajo (generation_create)
5. Consultar el estado del clip (generation_get)

Los créditos se gastan solo cuando un video se envía realmente, a los mismos precios de lista que picmovi.com. Listar modelos, cotizar y consultar no descuentan créditos.

MCP alojado (OAuth, posterior)

Cuando el host admita MCP remoto, el endpoint HTTP Streamable será:

{
  "mcpServers": {
    "picmovi": {
      "url": "https://picmovi.com/api/mcp"
    }
  }
}

Hasta que eso esté disponible, usa el adaptador stdio local a continuación. Llama a Agent REST en PICMOVI_BASE_URL (producción https://api.picmovi.com). Las claves y los IDs de fotos provienen de picmovi.com/mcp.

MCP stdio local

{
  "mcpServers": {
    "picmovi": {
      "command": "npx",
      "args": ["-y", "picmovi-mcp"],
      "env": {
        "PICMOVI_API_KEY": "${PICMOVI_API_KEY}",
        "PICMOVI_BASE_URL": "https://api.picmovi.com"
      }
    }
  }
}

Desde este repositorio durante el desarrollo, args debe ser una ruta absoluta a packages/mcp/dist/index.js (una ruta relativa se resuelve desde el directorio de inicio y falla):

{
  "mcpServers": {
    "picmovi": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/picmovi_mcp/packages/mcp/dist/index.js"],
      "cwd": "/ABSOLUTE/PATH/picmovi_mcp",
      "env": {
        "PICMOVI_MOCK": "1"
      }
    }
  }
}

PICMOVI_MOCK=1 ejecuta una prueba local en seco para que puedas conectar Cursor sin una clave activa. Aún así aplica cotizaciones de foto a video, idempotencia y un límite de paralelismo por cuenta. No lee tus créditos de picmovi.com.

Crea una clave en picmovi.com/mcp. Consulta docs/agent-api.md para el contrato REST que llama el adaptador.

Plantilla de prompt

Mismo texto que picmovi.com/mcp. Pégalo en el agente después de hacer clic en una foto en esa página. "Usa foto a video.…" selecciona el modelo (sin selector en el chat). El prompt de movimiento es el mismo texto i2v que escribes en el estudio — qué sucede en el clip. "movimiento sutil" es la intensidad del movimiento, no la historia. Elimina la línea del prompt de movimiento si solo quieres una animación genérica.

Animate my photo assetId: PASTE_ASSET_ID_HERE
for 5 seconds with subtle motion.
Use photo-to-video.seedance25 at 480p.
Motion prompt: She blinks slowly, a light breeze moves her hair, camera stays locked.
Quote credits first, then generate after I confirm.

CLI

npm run build
export PICMOVI_MOCK=1
node packages/cli/dist/index.js models list
node packages/cli/dist/index.js quote \
  --capability photo-to-video.seedance25 \
  --photo asset_start \
  --duration 5s \
  --resolution 480p

generate cotiza primero y requiere --yes --confirm-credits=<exact quote> más un --request-id estable al reintentar.

Flujo de trabajo de foto a video

1. Descubre. Llama a models_list. Elige un id devuelto, como photo-to-video.seedance25. No inventes un modelo.
2. Prepara la foto. Sube a través de una superficie confiable de PicMovi. Pasa assetIds.images[0] como foto inicial. Si las capacidades establecen endImageSupported, images[1] es el último fotograma opcional.
3. Cotiza. Llama a generation_quote con capabilityId, movimiento prompt, values (duración, resolución, cámara) y assetIds. Trata quotedCredits como autoritativo.
4. Confirma. Muestra al humano el monto exacto de créditos para crear un video a partir de esta foto. Un "genera" vago no es confirmación.
5. Crea una vez. Envía el mismo payload, confirmedCredits y un nuevo clientRequestId estable. Reutiliza ese id solo para la solicitud idéntica.
6. Consulta. Llama a generation_get. No crees de nuevo después de un tiempo de espera o submission_unknown.

Concurrencia

La misma cuenta de PicMovi no puede acumular trabajos de foto a video en paralelo sin límite. El servidor devuelve:

Código	Significado
parallel_limit_reached	Los trabajos en curso ya alcanzaron el límite del plan. Consulta hasta que uno termine.
queue_full	La cola de espera está llena. Intenta más tarde.
idempotency_conflict	clientRequestId se reutilizó con entrada diferente.
insufficient_credits	Créditos insuficientes para esta cotización de foto a video.
quote_changed	Confirma el nuevo quotedCredits antes de crear.

Las herramientas de solo lectura no ocupan espacios de concurrencia.

Desarrollo

npm install
npm test
npm run build

Paquetes:

• @picmovi/agent-core — catálogo de foto a video, cotizaciones, backend simulado
• @picmovi/client — cliente Agent REST v1
• picmovi-cli — adaptador de línea de comandos
• picmovi-mcp — adaptador MCP stdio local
• server.json — metadatos del Registro MCP alojado

Publicación de este listado

Envía el repositorio público de GitHub en https://mcpservers.org/submit. Detalles: docs/publishing.md. Contrato: docs/tool-contract.md. Plantilla de prompt: docs/prompt-template.md. Habilidad del agente: skills/picmovi-photo-to-video/SKILL.md.

Seguridad y licencia

No confirmes claves de API. El MCP alojado usa OAuth; los adaptadores locales leen PICMOVI_API_KEY del entorno. MIT-0, consulta LICENSE.