Tutorial
Como chamar kling-3.0-omni/transformation pela API da HiAPI: guia com curl e Python
Um passo a passo completo de requisições utilizáveis para conversão de estilo de vídeo na HiAPI
Nesta página
Funcionalidade e casos de uso do endpoint transformation
kling-3.0-omni/transformation é o endpoint de conversão de estilo de vídeo na HiAPI. Você fornece duas coisas a ele: um vídeo de origem e uma instrução de estilo em linguagem natural. Ele retorna um novo vídeo no qual o conteúdo do vídeo de origem é preservado, mas apresentado no estilo visual solicitado.
Pense nele como uma etapa de pós-produção escondida atrás de uma chamada HTTP. Você não precisa treinar um modelo, manter um cluster de GPUs ou gerenciar arquivos de checkpoint. Você descreve o efeito visual desejado, aponta para um vídeo, e o endpoint produz o resultado renderizado.
Cenários em que este endpoint é adequado
- Adicionar estilo a material existente. Você já tem uma tomada e quer que ela pareça animação, aquarela, granulação de filme, claymation ou outro efeito. O conteúdo e o movimento vêm do seu vídeo; o endpoint altera a textura da superfície.
- Manter um estilo consistente em lote. Como o estilo é expresso como instrução, você pode reutilizar o mesmo prompt em muitos vídeos de origem e obter um conjunto de resultados com estilo coerente.
- Validar o desenvolvimento de estilo por protótipo. Equipes criativas podem iterar direções de estilo com baixo custo antes de investir em fluxos de produção mais pesados.
Cenários em que não é adequado
- Você precisa gerar vídeo do zero (texto para vídeo é outra tarefa).
- Você precisa de edição, corte ou composição precisos quadro a quadro. A conversão apenas remodela o estilo, não faz edição.
- Seu material de origem é apenas áudio ou uma imagem estática.
O restante deste guia explica passo a passo a estrutura da requisição, uma chamada curl pronta para executar, a versão correspondente em Python e os detalhes operacionais em torno de saídas em 4K e tarefas longas.
Análise da requisição: vídeo de origem, instrução de estilo e opções de saída
Uma requisição de conversão não é complexa. Antes de escrever código, divida-a em três grupos de campos: vídeo de origem, instrução e configurações de saída.
Vídeo de origem
O endpoint precisa conseguir acessar sua entrada. Na prática, você passa uma URL que a plataforma consegue buscar ou um identificador retornado pela etapa de upload de arquivos da HiAPI. A regra prática é: o arquivo de origem deve ser acessível a partir do servidor, não a partir do seu notebook. Caminhos localhost ou arquivos atrás da sua VPN não funcionam.
O formato de origem deve ser conservador — use contêineres e codecs amplamente suportados. Se o seu vídeo foi gerado por um fluxo especial e não passa na validação, recodifique-o primeiro para MP4 H.264 padrão. Esse passo resolve boa parte dos erros de entrada.
Instrução de estilo
Esta é a descrição em linguagem natural do efeito visual desejado. É o campo de maior impacto na requisição e o que mais vale a pena refinar.
- Descreva o tratamento visual, não o conteúdo. O conteúdo vem do vídeo; dizer ao modelo o que já está na tela só desperdiça o orçamento do prompt.
- Seja específico quanto ao meio e à textura: “animação em claymation stop-motion com marcas de dedo visíveis” comunica muito mais do que “animação”.
- Quando for importante, deixe claro o que deve ser preservado: “mantenha os rostos reconhecíveis e o movimento de câmera inalterado”.
- Mantenha em um único parágrafo focado. Prompts longos e contraditórios tendem a resultar em algo sem graça por média.
Opções de saída
As configurações de saída controlam a resolução e outros detalhes de entrega. A principal decisão é solicitar 4K ou resolução padrão. Resolução mais alta consome mais computação e leva mais tempo, então trate isso como uma decisão consciente e não como padrão. Esse endpoint geralmente executa como tarefa assíncrona, então sua requisição normalmente retorna uma referência de tarefa que você deve consultar ou aguardar, em vez de retornar o arquivo final diretamente.
Mapeie primeiro sua entrada para esses três grupos de campos; o corpo JSON real da requisição ficará claro.
Uma requisição curl utilizável desde o início
A forma mais rápida de confirmar o entendimento é uma chamada mínima. A forma abaixo envia uma URL de vídeo de origem e uma instrução de estilo, e solicita resultado em resolução padrão. Substitua os valores de placeholder pelos seus próprios valores.
curl -X POST "https://api.hiapi.ai/v1/kling-3.0-omni/transformation" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": "Converter para animação em aquarela feita à mão, bordas com difusão suave, textura de papel visível, paleta quente e limitada. Preservar rostos e movimento de câmera.",
"resolution": "1080p"
}'
O papel de cada parte
- O caminho da URL especifica o endpoint. Precisa estar exatamente correto; um erro de digitação aqui retorna um erro de roteamento, não de validação.
- O cabeçalho
Authorizationcarrega sua chave da HiAPI. Exporte-a como variável de ambiente em vez de colá-la no histórico do shell. video_urlé o vídeo de origem. Precisa ser acessível pelo servidor.prompté a instrução de estilo. É o campo que você mais vai alterar.resolutioné a configuração de saída. Comece com resolução baixa durante a iteração e aumente depois de definir o efeito.
Interpretando a resposta
Uma resposta bem-sucedida retorna um objeto de tarefa. Registre o identificador da tarefa e quaisquer campos de status:
{
"id": "job_abc123",
"status": "queued"
}
Os nomes exatos dos campos devem ser lidos a partir da resposta real, não presumidos. O hábito importante é o mesmo em qualquer linguagem: analise o JSON, extraia o id da tarefa e trate o vídeo concluído como algo que chega depois. Não escreva código que presuma que a primeira resposta já contém um arquivo reproduzível.
A mesma requisição em Python
A versão em Python é a chamada curl com o corpo JSON expresso como dicionário. Usar requests mantém a legibilidade e as dependências leves.
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"video_url": "https://your-cdn.example.com/clips/source.mp4",
"prompt": (
"Converter para animação em aquarela feita à mão, bordas com difusão suave, "
"textura de papel visível, paleta quente e limitada. Preservar rostos e movimento de câmera."
),
"resolution": "1080p",
}
resp = requests.post(
f"{BASE}/kling-3.0-omni/transformation",
headers=HEADERS,
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
job_id = job["id"]
print("submitted", job_id, job.get("status"))
Consultar até a tarefa concluir
Como a renderização é assíncrona, envolva a espera em um loop com número limitado de tentativas e intervalo entre verificações. O intervalo deve ser folgado o suficiente para não sobrecarregar a API, e você deve definir um limite total de espera para que tarefas travadas não suspendam seu processo de trabalho.
def wait_for_job(job_id, max_attempts=60, interval=10):
for _ in range(max_attempts):
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "succeeded":
return data
if status == "failed":
raise RuntimeError(data.get("error") or "job failed")
time.sleep(interval)
raise TimeoutError(f"job {job_id} did not finish in time")
result = wait_for_job(job_id)
print(result.get("output") or result)
Deixando seguro para produção
- Leia o caminho do endpoint e a rota de consulta na documentação da resposta da API, em vez de codificar suposições que podem mudar.
- Registre o id da tarefa ao enviar. Se algo der errado posteriormente, é o seu único ponto de recuperação.
- Trate
failede timeout como resultados diferentes. Tarefas com falha geralmente indicam problema de parâmetro; timeouts geralmente indicam problema de capacidade ou duração.
Lidando com saídas 4K e tarefas de longa duração
Duas variáveis dominam o comportamento operacional deste endpoint: a resolução de saída e a duração da entrada. Planeje explicitamente para ambas.
Saída 4K
4K é uma decisão de entrega, não um padrão. Cada pixel de saída consome computação, e o salto relativo de resolução padrão para 4K é grande. Fluxo de trabalho recomendado:
- Itere a instrução de estilo em resolução mais baixa. A qualidade do prompt independe da resolução, então acerte o efeito primeiro com baixo custo.
- Trave o prompt e o vídeo de origem.
- Execute novamente uma vez em 4K para entrega.
Evite gerar variações em 4K em loop apertado enquanto ajusta o texto — essa é a forma mais comum de desperdiçar orçamento em renderizações que serão descartadas no final.
Tarefas de longa duração
Vídeos de origem mais longos levam mais tempo para converter, e o endpoint retorna uma referência de tarefa em vez do arquivo final. Construa seu cliente em torno dessa realidade:
- Nunca deixe uma requisição web ficar bloqueada na renderização. Envie, armazene o id da tarefa e retorne imediatamente ao chamador.
- Separe envio e consulta. Um processo de trabalho com fila e consulta periódica é mais robusto do que espera inline e sobrevive a reinícios do processo.
- Persista o estado da tarefa. Se o processo de trabalho morrer no meio da consulta, a tarefa não desaparece; você pode retomar a partir do id armazenado.
- Use webhook se sua conta oferecer suporte, mantendo a consulta periódica como caminho de fallback.
- Defina um orçamento total de espera que reflita o vídeo mais longo que você espera, e não um número arbitrário.
Um padrão prático
Divida vídeos de origem mais longos do que a duração típica em segmentos, converta cada um e depois una os resultados. Isso encurta o tempo de espera por chamada, permite repetir apenas um segmento em vez de toda a renderização e torna falhas baratas. Certifique-se de que as fronteiras dos segmentos não cortem movimento rápido, senão as emendas ficarão visíveis.
Diagnosticando falhas comuns
A maioria das falhas se enquadra em três categorias: vídeo de origem ilegível, parâmetro rejeitado ou tarefa que nunca conclui. Isole a categoria antes de mudar qualquer coisa.
Erros de upload e acesso à origem
Sintoma: o envio falha, ou a tarefa falha quase imediatamente por erro de entrada.
- URL não acessível publicamente. Teste a partir de uma máquina fora da sua rede. URLs assinadas expirando entre o envio e a busca são o culpado típico.
- Formato não suportado. Recodifique para MP4 H.264 padrão e tente novamente.
- Arquivo truncado ou corrompido. Baixe você mesmo e reproduza do início ao fim.
- Requisição grande demais. Se você está enviando bytes do arquivo inline em vez de uma URL, use o fluxo de upload e passe o identificador retornado.
Erros de parâmetro
Sintoma: resposta 4xx no envio.
- JSON malformado. Verifique o corpo com um linter. Vírgulas finais e aspas não escapadas são erros comuns em chamadas curl escritas à mão.
- Nome de campo ou tipo errado. Compare com o esquema de requisição atual; passar a resolução como número quando se espera uma string falha.
- Prompt vazio ou autocontraditório. Se a instrução não descreve nada, ou pede estilos mutuamente exclusivos, a saída tende a ser fraca ou rejeitada. Reescreva em torno de uma direção visual clara.
- Chave de API ausente ou inválida. Verifique o valor do cabeçalho e se a chave é válida para este endpoint.
Timeouts e tarefas travadas
Sintoma: a tarefa permanece em fila ou em execução depois do seu orçamento de espera, ou seu cliente desiste.
- Distinga timeout do cliente de falha da tarefa. Um timeout HTTP curto no envio não significa que a tarefa não começou; verifique se há id de tarefa antes de reenviar, senão você pode duplicar a renderização.
- Entradas longas e saídas 4K aumentam o tempo de execução. Se você continua atingindo timeout, reduza a resolução ou encurte o vídeo para confirmar que o fluxo funciona, depois ajuste de volta gradualmente.
- Se a tarefa reportar
failed, leia a mensagem de erro antes de tentar novamente. Repetir cegamente erros determinísticos de parâmetro só multiplica o custo.
Ordem eficaz de depuração
Comece com a menor requisição possível: um vídeo curto em resolução padrão e uma frase de prompt. Se funcionar, reintroduza um por um o prompt real, a duração real e, por fim, o 4K, alterando apenas uma variável por vez. A etapa que falhar mostrará qual variável é a causa.
Compensações de custo e latência a planejar
Depois que a requisição funciona, as decisões restantes são operacionais. Três alavancas afetam custo e latência ao mesmo tempo e interagem entre si.
Resolução
A resolução de saída é a maior alavanca individual. A cobrança está ligada ao trabalho de renderização executado, e saídas de resolução mais alta significam mais trabalho. Regra geral: iterar em resolução baixa, entregar em resolução alta. Nunca execute experimentos de estilo em 4K.
Duração da entrada
Vídeos de origem mais longos significam mais quadros para converter, portanto mais computação e mais tempo real. Se o seu caso de uso permitir, converta um clipe curto de destaque em vez de uma edição completa, ou divida material longo e converta apenas as partes que precisam de processamento.
Repetições
A menos que a falha ocorra antes do início da tarefa, cada repetição é uma renderização completa. É por isso que a ordem de depuração importa: valide os parâmetros com baixo custo antes de gastar com renderização. Evite envios duplicados registrando o id da tarefa e verificando antes de reenviar após um timeout do cliente.
Processamento em lote e paralelismo
Tarefas paralelas reduzem o tempo real, mas não o custo total — e podem atingir limites de concorrência. Para trabalhos em lote, uma fila moderada com paralelismo controlado costuma ser melhor do que fan-out. Ela mantém você abaixo dos limites de taxa, torna as falhas fáceis de repetir individualmente e oferece uma curva de gastos previsível.
Checklist de orçamento
- Defina o prompt em resolução baixa antes de qualquer renderização de entrega.
- Faça cache das saídas concluídas; não renderize novamente as mesmas entradas.
- Defina expectativas de gasto por tarefa e por lote, e alerte quando o lote ultrapassar.
- Acompanhe a duração das tarefas em relação à resolução e à duração da entrada para prever novos trabalhos a partir de execuções anteriores.
- Trate o 4K como a última etapa do fluxo, não como modo interativo.
Os preços deste endpoint estão listados no site da HiAPI, então consulte as tarifas atuais lá antes de planejar o tamanho do lote. Faça a menor requisição funcionar primeiro, depois escale resolução e duração de forma consciente — essa ordem mantém sua latência e sua fatura previsíveis.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio