Picmovi Photo to Video MCP

PicMovi Photo to Video MCP

Ferramentas de agente de código aberto para PicMovi, uma plataforma de foto para vídeo: transforme fotos estáticas em clipes curtos, ou crie vídeos a partir de fotos com um último quadro estático opcional.

Este repositório inclui um cliente REST tipado, uma CLI e um adaptador MCP stdio local. Identidade ao vivo, créditos, cotações, fotos proprietárias, concorrência do plano e trabalhos de vídeo são fornecidos pelo PicMovi Agent REST (/api/agent/v1/*). O MCP HTTP Streamable hospedado (/api/mcp + OAuth) é o caminho remoto-MCP posterior.

O que os agentes podem fazer

Agentes conectados podem:

1. Descobrir modelos de foto para vídeo (models_list)
2. Verificar créditos disponíveis (credits_get)
3. Cotar um trabalho de foto para vídeo (generation_quote) — sem cobrança
4. Após aprovação explícita de crédito, iniciar um trabalho (generation_create)
5. Consultar o clipe (generation_get)

Os créditos são gastos somente quando um vídeo é realmente enviado, pelos mesmos preços de tabela do picmovi.com. Listar modelos, cotar e consultar não deduzem créditos.

MCP hospedado (OAuth, posteriormente)

Quando o host suportar MCP remoto, o endpoint Streamable HTTP será:

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

Até que isso seja lançado, use o adaptador stdio local abaixo. Ele chama o Agent REST em PICMOVI_BASE_URL (produção https://api.picmovi.com). Chaves e IDs de fotos vêm 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"
      }
    }
  }
}

A partir deste repositório durante o desenvolvimento, args deve ser um caminho absoluto para packages/mcp/dist/index.js (um caminho relativo é resolvido a partir do diretório inicial e falha):

{
  "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 executa uma simulação local para que você possa configurar o Cursor sem uma chave ativa. Ele ainda aplica cotações de foto para vídeo, idempotência e um limite de paralelismo por conta. Ele não lê seus créditos do picmovi.com.

Crie uma chave em picmovi.com/mcp. Veja docs/agent-api.md para o contrato REST que o adaptador chama.

Modelo de prompt

Mesmo texto de picmovi.com/mcp. Cole no agente após clicar em uma foto nessa página. "Use photo-to-video.…" seleciona o modelo (sem seletor no chat). O prompt de movimento é o mesmo texto i2v que você digita no estúdio — o que acontece no clipe. "subtle motion" é a intensidade do movimento, não a história. Exclua a linha do prompt de movimento se quiser apenas uma animação 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 cotas primeiro e exige --yes --confirm-credits=<exact quote> além de um --request-id estável ao tentar novamente.

Fluxo de trabalho de foto para vídeo

1. Descubra. Chame models_list. Escolha um id retornado, como photo-to-video.seedance25. Não invente um modelo.
2. Prepare a foto. Envie por uma superfície confiável do PicMovi. Passe assetIds.images[0] como a foto inicial. Se o recurso definir endImageSupported, images[1] é o último quadro opcional.
3. Cote. Chame generation_quote com capabilityId, movimento prompt, values (duração, resolução, câmera) e assetIds. Trate quotedCredits como autoritativo.
4. Confirme. Mostre ao humano o valor exato de crédito para criar vídeo a partir desta foto. Um "gerar" vago não é confirmação.
5. Crie uma vez. Envie o mesmo payload, confirmedCredits e um novo clientRequestId estável. Reutilize esse id apenas para a solicitação idêntica.
6. Consulte. Chame generation_get. Não crie novamente após um tempo limite ou submission_unknown.

Concorrência

A mesma conta PicMovi não pode acumular trabalhos ilimitados de foto para vídeo em paralelo. O servidor retorna:

Código	Significado
parallel_limit_reached	Trabalhos em andamento já atingiram o limite do plano. Consulte até um terminar.
queue_full	A fila de espera está cheia. Tente mais tarde.
idempotency_conflict	clientRequestId foi reutilizado com entrada diferente.
insufficient_credits	Créditos insuficientes para esta cotação de foto para vídeo.
quote_changed	Confirme o novo quotedCredits antes de criar.

Ferramentas somente leitura não ocupam slots de concorrência.

Desenvolvimento

npm install
npm test
npm run build

Pacotes:

• @picmovi/agent-core — catálogo de foto para vídeo, cotações, backend simulado
• @picmovi/client — cliente Agent REST v1
• picmovi-cli — adaptador de linha de comando
• picmovi-mcp — adaptador MCP stdio local
• server.json — metadados do MCP Registry hospedado

Publicando esta listagem

Envie o repositório público do GitHub em https://mcpservers.org/submit. Detalhes: docs/publishing.md. Contrato: docs/tool-contract.md. Modelo de prompt: docs/prompt-template.md. Habilidade do agente: skills/picmovi-photo-to-video/SKILL.md.

Segurança e licença

Não faça commit de chaves de API. O MCP hospedado usa OAuth; adaptadores locais leem PICMOVI_API_KEY do ambiente. MIT-0, veja LICENSE.