API Genjutsu: Envie um Vídeo de Troca de Objeto
Use a API Genjutsu para uma solicitação de Object Swap: prepare um clipe de origem, envie o job e recupere o vídeo editado.

Um recurso de edição de vídeo pode retornar um job bem-sucedido e ainda assim deixar sua equipe com um ativo inutilizável: a parte errada do clipe foi processada, a substituição muda entre os quadros ou ninguém salvou o resultado. Em uma integração com a API Genjutsu, eu tornaria cada edição rastreável, da entrada até o arquivo aprovado. O início rápido da API da Higgsfield descreve o fluxo de enviar, consultar e recuperar; este guia o aplica a uma única requisição de Object Swap.
A Higgsfield fornece o modelo e o endpoint. Se o seu produto usa a WaveSpeedAI, verifique no diretório de modelos dela se existe essa operação exata e consulte o schema de requisição próprio. Não presuma que outro modelo de troca em vídeo aceite uma requisição da Higgsfield.

O que uma requisição de Object Swap do Genjutsu precisa?
Uma requisição precisa de uma URL de vídeo de origem e de uma a oito URLs de imagens de referência. O prompt é opcional. O valor padrão de resolution é 720p; 480p e 1080p também constam na lista. A referência da API de Object Swap identifica o modelo como higgsfield/genjutsu/object-swap/v1.0. Ele exige um vídeo com pelo menos quatro segundos e pelo menos 409.600 pixels por quadro.
Verifique o clipe antes de enviá-lo. Vídeos com mais de 30 segundos são cortados em 30 segundos, e o resultado segue essa duração preparada. Se a edição pretendida ocorre no segundo 34, uma requisição bem-sucedida continua sem conseguir entregá-la. Selecione o trecho primeiro e registre qual trecho você enviou.
Uma requisição do lado do servidor pode ter este formato. As URLs e as variáveis de ambiente são ilustrativas:
curl -X POST \
"https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
-H "Authorization: Key ${HF_KEY}" \
-H "Idempotency-Key: ${EDIT_ID}" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/approved-source.mp4",
"image_urls": ["https://example.com/approved-object.png"],
"prompt": "Replace the featured cup with the reference cup.",
"resolution": "720p"
}'
Mantenha a credencial no seu servidor. Dê a cada edição lógica sua própria chave de idempotência estável, para que um envio ambíguo possa ser repetido sem criar deliberadamente um segundo job. Se a origem mostra uma pessoa identificável, ou usa filmagens ou arte protegidas, obtenha os direitos e o consentimento necessários antes de enviá-la. Este é um lembrete de produção, não aconselhamento jurídico.
Envie a edição e acompanhe o status
Um POST bem-sucedido aceita o trabalho; ele não retorna um vídeo finalizado. Salve request_id, status_url e cancel_url da resposta no registro de edição do seu produto. Use essas URLs retornadas em vez de construí-las você mesmo.
A documentação do ciclo de vida das requisições da Higgsfield lista queued e in_progress como estados não terminais. Pare de esperar quando o status passar a completed, failed, nsfw ou canceled. Mostre esses resultados separadamente na sua interface. “Ainda processando” é um feedback ruim quando o provedor já rejeitou o job.

Comece a consultar em intervalos de aproximadamente dois segundos e depois aumente o intervalo se a espera for mais longa. Se uma consulta de status encontrar um erro de rede transitório, repita a consulta de status. Não envie outro POST de edição só porque uma consulta falhou. Salve o status final e qualquer erro retornado junto com o ID da requisição, para que o suporte consiga distinguir uma geração que falhou de uma sessão do navegador encerrada antes da hora.
Recupere e verifique o vídeo finalizado
Quando o status for completed, leia video.url no resultado. Baixe o arquivo para um armazenamento que seu produto controle e verifique se ele reproduz e corresponde à edição pretendida. Um job de API concluído é um candidato à entrega, não uma decisão de aprovação.
Revise mais do que uma miniatura. Verifique a substituição no início, no meio e no fim do clipe, especialmente quando o objeto passa atrás de outro elemento ou atravessa o quadro. Compare a duração processada com o trecho que você enviou. Se o som importa para o recurso, inspecione também a faixa de áudio do resultado; a referência de Object Swap não promete a manutenção do áudio de origem.
Um bom resultado isolado não significa que o fluxo de produção está pronto. A conclusão pelo provedor indica que existe um arquivo. Quem decide se esse arquivo pode entrar no produto é a sua verificação de aceitação.
Torne o Object Swap reproduzível em produção
Salve um manifesto de edição que permita repetir o processo
Mantenha juntos a versão do ativo de origem, o intervalo de tempo selecionado, as versões das imagens de referência, o prompt, a resolução, o ID do modelo, a chave de idempotência, o ID da requisição e o status final. Acrescente o local de armazenamento do resultado aprovado. Uma pessoa consegue lembrar os parâmetros. Uma equipe, não.
Esse registro ajuda quando um editor pede “a mesma troca, mas com o produto azul”. A equipe pode alterar uma entrada de propósito, em vez de reconstruir a requisição anterior a partir de um arquivo chamado final-v3.mp4.
Arquive o original e o resultado aprovado
Guarde o clipe original para reverter e salve o resultado aprovado fora do local temporário de mídia do provedor. Os termos da API sobre retenção e consentimento da Higgsfield dizem que a mídia gerada fica disponível por pelo menos sete dias, mas pode ser excluída depois disso. Isso não é uma garantia de URL permanente. Registre se o resultado foi aceito, rejeitado ou devolvido para revisão, e o motivo.
Perguntas frequentes

O Object Swap mantém o áudio do clipe de origem?
A referência publicada do Object Swap não diz. Não prometa a passagem do áudio no seu produto. Teste com um clipe autorizado que tenha uma faixa de áudio reconhecível e inspecione o arquivo retornado antes de afirmar esse recurso.
É possível cancelar uma requisição Genjutsu que está na fila?
Sim, enquanto ela continuar elegível na fila. Envie uma requisição de cancelamento para a cancel_url retornada; apenas parar o seu poller não cancela o job. Depois que o processamento começa, o cancelamento deixa de estar disponível no ciclo de vida documentado.
O que acontece se a URL de origem expirar durante a preparação?
A documentação não especifica um ponto único de falha para a expiração de uma URL de entrada do Object Swap. Mantenha a origem acessível enquanto a Higgsfield puder precisar buscá-la. Se a preparação falhar, registre o status e o erro reais da requisição. A aceitação do POST não prova que o arquivo já havia sido baixado.
Uma falha na preparação da entrada consome unidades de cobrança?
Depende da falha informada. A orientação sobre cobrança e retenção da Higgsfield diz que requisições que terminam em failed ou nsfw não são cobradas e que os créditos reservados são devolvidos. “Falha na preparação da entrada” não é um status de cobrança por si só, então verifique a resposta e o registro de cobrança em vez de aplicar a mesma regra a todo erro desse tipo.
Por quanto tempo a URL do vídeo concluído permanece disponível?
A mídia gerada fica acessível por pelo menos sete dias e pode ser removida depois. Baixe um vídeo aprovado sem demora. Para um recurso da API Genjutsu que os usuários possam rever semanas depois, sirva a cópia salva no seu próprio armazenamento.
Posts anteriores:
/filters:quality(82)/media/images/1773962750383987480_n3hqzHRZ.webp)
/filters:quality(82)/media/images/3439779b-d7cf-42fd-958d-8711fe2abdf4.webp)