Introdução
O Video Head Swap Analysis lê um clipe e devolve uma prévia por cabeça que consegue acompanhar, em ordem fixa: a primeira imagem é a posição 0, a segunda é a posição 1, e assim por diante. São essas posições que a chamada de troca recebe: você olha as imagens e devolve os números.
Aqui nada é gerado e o clipe não é alterado. Esta chamada produz a lista de alvos com que a chamada de troca trabalha, e é o único jeito de descobrir quantas cabeças existem em uma tomada e qual é qual.
Análise de vídeo do Head Swap → Edição de vídeo do Head Swap
Recursos e destaques
Você escolhe por imagem, não por coordenada
A maioria dos endpoints de troca faz você descrever de quem estava falando, ou então adivinha. Aqui a análise entrega os candidatos como imagens numeradas. A dúvida sobre quem vai ser trocado se resolve antes de qualquer coisa ser gerada, que é também o momento em que errar ainda sai de graça.
Uma análise alimenta várias trocas
O resultado continua servindo por 24 horas. Escale uma pessoa, olhe como ficou e depois mande outro conjunto de fotos de referência contra a mesma análise: a análise você paga uma vez só. Passadas as 24 horas as referências vencem e o clipe precisa ser analisado de novo.
Lê o material do jeito que foi filmado
O rastreamento acompanha cada cabeça através de cortes, giros e oclusões parciais. São aceitos clipes de 5 a 30 segundos, e a análise relata cada cabeça que consegue segurar ao longo da tomada, não só a que está na frente.
Parâmetros da requisição
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
video_url | Sim | O clipe a analisar, de 5 a 30 segundos. Guarde exatamente esta URL: a chamada de troca precisa rodar sobre o mesmo vídeo e a copia daqui automaticamente se você a omitir lá. pelo menos 1 caracteres |
resolution | Não | Resolução de rastreamento. A chamada de troca precisa usar o mesmo valor, então escolha a resolução que o clipe final deve ter. |
Preços
$0.08 / análise
A análise e a troca são cobradas separadamente.
Casos de uso
Conferir um clipe antes de pagar para trocá-lo
A chamada de troca custa mais do que a análise. Rodar a análise primeiro diz se as cabeças que interessam a você são mesmo rastreáveis neste material: desfoque forte, oclusões longas e sujeitos que saem de quadro aparecem como uma prévia faltando ou instável.
Escolher uma só pessoa no meio de várias
Analise uma cena com várias pessoas em quadro, leia as prévias e devolva só a posição que você queria. A troca deixa todas as outras intactas.
Manter o mesmo elenco em toda uma série
Gere um lote de clipes com qualquer modelo de vídeo, analise cada um e use as prévias para alinhar o mesmo alvo em todas as tomadas, para que a série seja lida como algo contínuo.
Qualquer tema, com intérprete que consentiu
Nada muda na requisição, seja qual for o conteúdo do material. A exigência de autorização descrita nos limites mais abaixo também não muda: é uma condição rígida, não uma classificação de conteúdo.
Guia de prompt e dicas práticas
Use a mesma resolução nas duas chamadas
Escolha a resolução que o clipe pronto deve ter e use a mesma aqui: a chamada de troca precisa rodar no mesmo valor. Ela não muda o que esta chamada detecta, só o quadro em que a troca trabalha.
Leia a ordem das prévias, não a presuma
As imagens voltam ordenadas, mas a ordem vem do rastreamento, não do lugar na tela nem de quem aparece mais. A pessoa mais à esquerda não é necessariamente a posição 0. Olhe as imagens.
Mande o mesmo vídeo para as duas chamadas
A chamada de troca precisa do clipe idêntico: mesmo arquivo, mesma codificação. Deixe video_url de fora na requisição de troca e ele é copiado da análise, que é o jeito mais seguro de garantir que os dois batam.
Analise de novo se o material mudar
Recodificar, cortar ou reexportar o clipe invalida a análise: as posições deixam de apontar para as mesmas cabeças. Analise o arquivo que você vai trocar de verdade.
Início rápido da API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/head-swap-video-v1/video-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Consulte a referência da API para autenticação, esquema completo, polling e tratamento de erros.
