sailtonight/kaloclip-skill

Criação de vídeos com IA Kaloclip (clip)

O Kaloclip transforma informações e imagens de produtos em um roteiro de vídeo curto, e um roteiro em um vídeo finalizado. A conta é a mesma que possui a chave da API: seus créditos, sua assinatura Kaloclip (tamanho da fila de vídeos, marca d'água no plano Gratuito), seus recursos de imagem e trabalhos. A maioria dos comandos é gratuita. Os comandos [credits] enviam trabalhos pagos — veja "Gastando créditos" antes de usá-los.

Executar

A CLI está incluída neste skill (scripts/clip.py, apenas stdlib do Python 3.11+ — nada para instalar):

python3 <diretorio-deste-skill>/scripts/clip.py opcoes

Todos os exemplos abaixo escrevem clip como abreviação de python3 <diretorio-deste-skill>/scripts/clip.py.

A saída é TOON (token-oriented) no stdout; adicione --json a qualquer comando para JSON bruto. Erros são estruturados no stdout com linhas help: acionáveis. Códigos de saída: 0 ok, 1 erro, 2 uso.

Configuração — verifique isso antes da primeira chamada

Todo comando precisa de uma chave de API KaloData Open (enviada como cabeçalho secret-key). É a mesma chave que a CLI kalo do skill kalodata usa, armazenada no mesmo local. Antes da primeira chamada de uma sessão, execute clip config e veja api_key. Se disser missing, pare — não adivinhe uma chave e não tente novamente. Guie o usuário por estas etapas e aguarde:

1. Obter uma chave — faça login em https://www.kalodata.com/open-center/account e clique em gerar chave. Não tem conta? Registre-se em https://www.kalodata.com/open-center/home primeiro.

2. Salvá-la — clip config set --key <API_KEY> (armazenada em ~/.config/kalodata/config.toml, modo 0600, compartilhada com kalo), ou defina KALODATA_API_KEY no ambiente.

3. Créditos — o mesmo saldo de créditos do KaloData; os preços e regras de assinatura do Kaloclip se aplicam. clip credit mostra o saldo.

   chamada	créditos
   options, credit, product resolve, image upload/import, video preview, qualquer get / job	grátis
   script create	2
   video create	o que video preview disser para o modelo/duração/resolução (ex.: sd2 · 15s · 720P = 28)
   analysis create	o preço do Kaloclip para uma análise de roteiro

Comandos

comando	o que faz
clip options	modelos, durações, resoluções disponíveis no momento; qual modelo permite qual duração
clip credit	créditos restantes
clip product resolve <link>	link do produto → título, categorias, pontos de venda, recursos de imagem
clip image upload <arquivo...>	1–6 imagens locais (JPEG/PNG/GIF/WebP, ≤5MB) → ids de recurso
clip image import <url...>	1–6 URLs de imagem https públicas → ids de recurso
clip script create	[credits] rascunhar um roteiro; --product-link, ou --image --title --category
clip script get <job_id>	estado do rascunho e texto do roteiro; --wait
clip script candidates <job_id>	os dois candidatos de um trabalho de reescrita feito no site Kaloclip
clip video preview	créditos que um vídeo custaria; --model --duration --resolution --ratio
clip video create	[credits] roteiro final → vídeo; --script-job / --script-file / --script
clip video get <job_id>	estado do vídeo; videoUrl quando concluído; --wait
clip analysis create <url_do_video>	[credits] análise quadro a quadro de um vídeo existente; --commerce --country
clip analysis get <job_id>	estado e resultado da análise (mantido por 30 dias); --wait
clip job <job_id>	estado e saída de qualquer trabalho; --wait
clip config	mostrar/definir chave (compartilhada com kalo) e endpoint (--base-url staging)

O fluxo do vídeo

1. clip options — escolha --model e --duration juntos a partir de sua saída. Modelos e suas durações mudam; nunca use um modelo de memória.
2. Material do produto, ou:
   • clip product resolve <link> para verificar o que o link produz, depois passe o mesmo --product-link para script create; ou
   • as próprias imagens do usuário: clip image upload a.png b.jpg → --image ASSET_ID=IMAGE_URL (repita, 1–6), mais --title e --category.
3. Pergunte como o vídeo deve ser (tom, cena, gancho) e passe como --description.
4. clip script create --product-link <link> --model <M> --duration <S> --description "..." → uma simulação. Mostre-a, obtenha um sim, execute novamente com --yes --idempotency-key <chave da dica> --wait (um rascunho leva cerca de 30–60s; os créditos são cobrados no envio).
5. Mostre o roteiro. Para alterá-lo, escreva o texto editado em um arquivo e use --script-file.
6. clip video create --script-job <job_id> [--script-file editado.txt] [--resolution 1080P] → uma simulação que inclui o custo em créditos. Obtenha um sim, execute novamente com --yes --idempotency-key <chave>.
7. clip video get <job_id> --wait — um vídeo de 15 segundos leva cerca de 15 minutos (--wait pesquisa por até 20). Informe ao usuário que está em execução; se --wait expirar, pesquise novamente — nunca reenvie. Entregue videoUrl (mp4) e coverImageUrl ao usuário.

--script-job reutiliza as imagens, título, modelo e duração com que o rascunho foi enviado quando o rascunho foi feito nesta máquina; caso contrário, passe-os novamente (--product-link cobre a maior parte).

Gastando créditos

Comandos [credits] nunca agem na primeira execução: sem --yes eles imprimem a requisição exata (dry_run:), seu custo em créditos e uma chave de idempotência, e não enviam nada. Mostre ao usuário, obtenha um sim explícito, então execute novamente com --yes --idempotency-key <chave>. Nunca adicione --yes por conta própria e nunca reenvie em loop.

• Reintentativa: se um envio terminar com "outcome is unknown" (timeout / 5xx / SUBMISSION_IN_PROGRESS), execute novamente o comando idêntico com a mesma --idempotency-key dentro de 5 minutos — o Kaloclip então retorna o trabalho original em vez de cobrar novamente. Uma nova chave significa um novo trabalho pago. SUBMISSION_OUTCOME_UNKNOWN: pare e informe o usuário; não reenvie.
• Trabalhos são assíncronos: mantenha o id do trabalho; pesquise com --wait (a cada 5s). Nunca reenvie um trabalho que esteja queued ou processing.
• TASK_QUEUE_FULL: a fila de vídeos da assinatura está cheia (Gratuito: um vídeo por vez). Nada foi cobrado; aguarde o vídeo em execução e envie novamente.
• RATE_LIMIT_EXCEEDED: limites por usuário (uploads/imports 10/min, resolução de produto 10/min, visualização 20/min, vídeos 5/min) — aguarde pelo menos 60 segundos.

Análise de roteiro

clip analysis create <url tiktok|kalodata|youtube-shorts> divide um vídeo em cenas (video_scripts[]: tempo, escala do plano, descrição visual, narração, cada um com uma tradução), além do gênero do apresentador, idioma falado, movimentos de câmera e por que funciona. Vídeos TikTok compráveis: adicione --commerce --country US. Os resultados permanecem legíveis por 30 dias (clip analysis get <job_id>); adicione --json para todos os campos. Use para aprender com um vídeo viral antes de rascunhar seu próprio roteiro.

Lendo os dados corretamente

• O roteiro de um rascunho concluído é uma direção longa (talento, estilo, cena, VISUAL / ÁUDIO / AÇÃO DO TALENTO por cena). Mostre-o por completo; não o resuma antes da aprovação do usuário.
• video preview é uma estimativa; um envio ainda pode ser recusado (fila, assinatura, entradas).
• videoUrl é o arquivo finalizado; vídeos de assinatura Gratuita têm marca d'água.
• selling_points de product resolve pode estar vazio enquanto o Kaloclip ainda está analisando o produto — execute novamente em um minuto ou prossiga sem elas.
• Recursos de imagem pertencem à conta; ids de recurso de uma chave não funcionam com outra.