Tutorial
Como usar topaz-upscale/video pela API HiAPI: exemplos em curl e Python
Nesta página
O que topaz-upscale/video faz e quando usá-lo
topaz-upscale/video é um endpoint de aprimoramento de vídeo na HiAPI. Você envia um vídeo de origem e instruções, e ele retorna o vídeo aprimorado: com resolução maior, detalhes finos reconstruídos e, opcionalmente, movimento mais suave por meio de interpolação de quadros. Use este endpoint quando o material já existe e o problema é qualidade, não geração de conteúdo.
Cenários de uso
Tarefas típicas que combinam naturalmente com este endpoint:
- Acervo e material antigo — gravações antigas, capturas de tela compactadas ou mídia herdada que precisa parecer apresentável em resoluções modernas.
- Pipelines de renderização — sequências já concluídas que foram renderizadas em baixa resolução por velocidade e depois aprimoradas para entrega.
- Limpeza de movimento — fontes com baixa taxa de quadros precisam de quadros interpolados para evitar travamentos na reprodução.
- Variantes de entrega — um master e múltiplos níveis de saída, com aprimoramento aplicado separadamente em cada nível.
Quando escolhê-lo em vez de alternativas
A decisão geralmente se resume a três perguntas:
- O problema é resolução e detalhe, ou conteúdo? Se você precisa inventar novos pixels (cenas que nunca foram filmadas), esta é a ferramenta errada. O aprimoramento pressupõe quadros de origem reais por baixo.
- Seu pipeline tolera trabalho assíncrono? Tarefas de vídeo não são instantâneas. Se a experiência do usuário exige respostas em menos de um segundo, este endpoint deve ficar em uma tarefa em segundo plano, não no manipulador de requisições.
- Você precisa de interpolação de quadros e upscale? Se a suavidade do movimento importa, você quer as duas capacidades em um único processamento, em vez de encadear ferramentas separadas.
topaz-upscale/videocobre ambas.
Se sua origem for uma única imagem estática, use antes um upscaler de imagens. Se a origem estiver boa mas a codificação ruim, corrija a codificação primeiro — o aprimoramento não recupera detalhes que a compressão pesada já destruiu, e você pagará por computação sem ganho de qualidade.
Preparando a requisição antes da primeira chamada
A maioria das falhas na primeira chamada vem de peças ausentes, não de prompts ruins. Antes de escrever qualquer código, prepare estes itens.
Conta e credenciais
Você precisa de uma chave de API da HiAPI com acesso a topaz-upscale/video. Guarde a chave em uma variável de ambiente, nunca no código-fonte — todos os exemplos abaixo leem HIAPI_API_KEY do ambiente.
export HIAPI_API_KEY="your-key-here"
Mídia de origem acessível
O modelo precisa conseguir obter sua entrada. Dois modos confiáveis:
- URL pública ou assinada — uma URL que o serviço possa baixar sem autenticação interativa. Se seu armazenamento exige links assinados, gere um link com validade folgada e lembre-se de regenerá-lo nas novas tentativas, caso contrário tarefas longas falharão no meio.
- Upload prévio — envie o arquivo pelo mecanismo de upload da plataforma e referencie o identificador retornado. Para arquivos grandes e qualquer conteúdo atrás de rede privada, esta é a opção mais segura.
Características da origem que vale a pena verificar
Antes de gastar uma chamada, confirme:
- Duração. Vídeos longos implicam tarefas longas. Se estiver testando, extraia um trecho de 5–10 segundos do meio da origem — o meio costuma ser mais representativo do que os primeiros quadros.
- Codec e contêiner. Codecs raros às vezes não podem ser decodificados. Em caso de dúvida, remuxe para um contêiner comum.
- Taxa de quadros. Registre a taxa exata; você precisará dela ao inferir a interpolação de quadros.
- Resolução. Registre as dimensões exatas da origem para que sua comparação antes/depois seja honesta.
Defina claramente seu objetivo de saída
Decida a resolução e a taxa de quadros de saída antes da primeira chamada, não depois. Uma configuração de aprimoramento razoável para uma origem 720p indo para 1080p é diferente de uma origem 480p indo para 4K. Anote o destino; você vai reutilizá-lo em cada requisição seguinte.
Fazendo a chamada com curl
A requisição é um POST com corpo JSON enviado ao endpoint topaz-upscale/video. Abaixo um exemplo completo e executável — substitua pela URL da sua própria mídia.
curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "topaz-upscale/video",
"input": {
"video": "https://your-bucket.example.com/clips/source_720p.mp4"
},
"parameters": {
"target_resolution": "1080p",
"target_fps": 60,
"interpolation": "smooth",
"detail": "balanced"
},
"prompt": "Restaurar texturas finas em tecido e pele, manter o grão natural, interpolar para 60fps sem fantasmas"
}'
Interpretando a resposta
A resposta imediata confirma a tarefa. Você recebe um identificador de tarefa e um campo de status. O trabalho de vídeo é assíncrono, então o padrão real é:
# 1. Enviar e capturar o id da tarefa
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | jq -r '.id')
# 2. Consultar até o status ser terminal
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'
Ao ler o resultado, três campos importam:
status— passa de enfileirado para em execução e então para um estado terminal. Trate qualquer status não reconhecido como "continue aguardando", nunca como sucesso.output— presente em caso de sucesso, contém a URL ou o identificador do vídeo aprimorado.error— presente em caso de falha. Leia a mensagem literalmente; ela geralmente indica o campo problemático.
Se estiver iterando sobre prompts, coloque o corpo da requisição em um arquivo (request.json) e use -d @request.json. Isso mantém o histórico do shell limpo e permite comparar versões diferentes da mesma requisição.
Chamando o mesmo endpoint a partir do Python
A versão em Python é um invólucro fino sobre o mesmo contrato HTTP. Use requests, mantenha a chave no ambiente e envolva o envio e o laço de consulta em funções, para que quem chama não precise saber que é assíncrono.
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def enhance_video(
video_url: str,
prompt: str,
target_resolution: str = "1080p",
target_fps: int = 60,
poll_interval: float = 5.0,
timeout: float = 1800.0,
) -> str:
payload = {
"model": "topaz-upscale/video",
"input": {"video": video_url},
"parameters": {
"target_resolution": target_resolution,
"target_fps": target_fps,
"interpolation": "smooth",
"detail": "balanced",
},
"prompt": prompt,
}
resp = requests.post(f"{BASE}/video/enhance",
headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()
job_id = resp.json()["id"]
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
data = r.json()
if data["status"] == "succeeded":
return data["output"]["video"]
if data["status"] == "failed":
raise RuntimeError(data.get("error", "Falha no aprimoramento"))
time.sleep(poll_interval)
raise TimeoutError(f"Tarefa {job_id} não concluída no tempo esperado")
Cuidados ao usá-lo em um pipeline real
- Consulta com backoff exponencial. Intervalo fixo de cinco segundos serve para scripts de shell; em produção, faça backoff e limite o intervalo máximo. Vídeos longos podem levar um tempo; consultar com mais frequência não os fará terminar mais rápido.
- Idempotência. Se a chamada de envio expirar, você pode não saber se a tarefa foi iniciada. Registre o corpo da requisição junto com o id da tarefa para identificar duplicatas, em vez de reenviar às cegas.
- Persista o id da tarefa. Grave-o no banco de dados assim que o receber. Se o processo morrer no meio da consulta, você poderá retomar pelo id sem pagar por um segundo aprimoramento.
Receitas de prompt para interpolação de quadros
A interpolação de quadros é onde os prompts mais erram — ou são vagos demais para orientar qualquer coisa, ou prescritivos demais, levando o modelo a perseguir objetivos contraditórios. O prompt coexiste com parâmetros estruturados; deixe a redação tratar de intenção e características do movimento, e os parâmetros carregarem os alvos numéricos.
Padrão: descreva o movimento, não a matemática
Ruim:
interpolate
Melhor:
Interpolar para 60fps suaves. Manter o ritmo original do movimento — sem alterar a velocidade. Panning e movimento de câmera devem ser lineares e estáveis; evitar distorção nas bordas dos quadros.
Você já informou a taxa de quadros alvo em parameters. O prompt deve descrever como é o movimento suave para este material.
Padrão: nomeie os artefatos a evitar
Suavizar 24p para 60fps. Evitar fantasmas em mãos em movimento rápido, evitar arrasto ao redor de objetos finos como grades e cabelos. O fundo estático deve permanecer totalmente imóvel.
Nomear modos de falha específicos é muito mais eficaz do que "alta qualidade". O modelo pode verificar sua própria saída contra instruções concretas.
Padrão: separe movimento de textura
Nesta rodada, foque apenas na suavidade do movimento. Mantenha os detalhes e o grão existentes intactos — a restauração de textura é tratada separadamente.
Útil quando você encadeia duas etapas de processamento, de modo que cada prompt tenha uma única responsabilidade.
Padrão: lidar com material de movimento misto
Para uma entrevista com câmera fixa mas sujeito em movimento, indicar explicitamente que a câmera está parada funciona bem:
Interpolar para 60fps. Câmera fixa — o fundo deve ficar completamente imóvel ou tremular. Apenas a cabeça e as mãos do falante devem mostrar movimento suave.
Resista à tentação de escrever longos tratados. Três frases cobrindo o movimento alvo, os artefatos a evitar e o que deve permanecer estático cobrem quase todos os casos.
Receitas de prompt para reconstrução de detalhes
A reconstrução de detalhes é a metade da tarefa que inventa estruturas finas plausíveis. O modo de falha é a textura alucinada: pele que parece plástico, vegetação que vira ruído, texto que vira rabisco. O prompt deve colocar limites na invenção.
Padrão: ancore na origem
Reconstruir detalhes consistentes com os quadros de origem. Não inventar texturas que os pixels originais não sugerem. Onde o detalhe realmente se perdeu, preferir um resultado suave e crível a ruído nítido.
Essa única instrução previne a maioria das patologias de supernitidez.
Padrão: nomeie os materiais na cena
Restaurar detalhes finos de textura de tecido, fios de cabelo e poros da pele. Manter tons de pele naturais e poros irregulares — evitar aparência lisa, como se fosse aerografada. Superfícies metálicas devem manter os realces existentes, sem criar novos realces.
Instruções direcionadas a materiais dão ao modelo restrições acionáveis, sem precisar de um parágrafo inteiro de generalidades.
Padrão: proteger texto e gráficos
Este trecho contém legendas na tela e logotipos. O texto deve permanecer legível e sem distorções. Não redesenhar nem alterar o estilo de nenhum elemento gráfico.
Texto é o detalhe de maior risco — legendas ilegíveis são piores do que legendas levemente borradas. Se a legibilidade for crítica, valide na etapa de comparação, em vez de confiar no prompt.
Padrão: ajuste a nitidez intencionalmente
Aplicar uma quantidade contida de restauração de detalhes. O objetivo é material com aparência natural em 1080p, não um quadro estático supernitidizado. Uma leve suavidade é aceitável; ringing e halos não são aceitáveis.
Combinando as duas
Quando você interpola e reconstrói no mesmo processamento, escreva um único prompt cobrindo ambos, mas cada oração aborda apenas uma preocupação:
Reconstruir texturas finas — tecido, cabelo, pele — consistentes com a origem, evitando suavidade plástica. Interpolar para 60fps com movimento estável, sem fantasmas nas mãos e fundo totalmente estático.
Comparando a saída antes e depois
Um vídeo aprimorado que parece excelente em um único quadro pode desmoronar em movimento. Estabeleça um fluxo de comparação fixo e execute-o sempre que mudar parâmetros ou prompts; caso contrário, você estará adivinhando, e adivinhar sai caro.
Monte um conjunto padrão de clipes de teste
Escolha três clipes curtos (5–10 segundos cada) que nunca mudam:
- Fácil — bem iluminado, movimento lento, origem limpa. Deve parecer quase perfeito; se não, algo está configurado errado.
- Difícil — movimento rápido, detalhes finos ou tipos de movimento mistos. Artefatos de interpolação aparecerão aqui.
- Adversarial — texto na tela, estruturas finas ou compressão pesada anterior. Alucinações aparecerão aqui.
Execute os três para cada mudança de prompt ou parâmetro. Uma mudança que ajuda o clipe fácil mas prejudica o adversarial não é uma melhoria.
Compare nesta ordem
- Comparação lado a lado a 100% de zoom. Não use ajuste à janela, pois os artefatos se escondem. Verifique as mesmas regiões recortadas: rostos, áreas de texto e áreas de alto movimento.
- Arraste quadro a quadro. Avance quadro a quadro nas partes de movimento rápido em busca de fantasmas, distorções e cintilação.
- Reprodução em velocidade real. Muitos artefatos desaparecem ao arrastar quadro a quadro e aparecem em movimento, e vice-versa. Veja os dois.
- Verificação de legibilidade de texto. Leia cada legenda na versão aprimorada comparando com a origem. É a verificação objetiva de passa/falha mais rápida disponível.
Qualidade e custo juntos
A cobrança acompanha o trabalho do endpoint — duração e resolução da saída são os fatores determinantes; consulte o painel de preços do site para as tarifas atuais. Consequência prática: clipes mais longos trazem ganho marginal de qualidade e costumam ser menos vantajosos do que clipes mais curtos com ganho visível. Para cada configuração candidata, registre a duração e a resolução de saída geradas e pergunte se a melhoria visível vale o custo. Guarde os vencedores, descarte o resto e, antes de conectar o endpoint a um pipeline automatizado, congele uma configuração e documente-a — prompt, parâmetros e resultados dos testes — para que mudanças futuras possam ser medidas.
Solucionando problemas comuns de requisição
A maior parte do atrito de integração com topaz-upscale/video cai em poucas categorias. Trate-as nesta ordem.
Autenticação e acesso
401 significa chave ausente, malformada ou não enviada — verifique se a variável de ambiente está de fato definida no shell que executa o comando, não apenas no editor. 403 geralmente significa que a chave é válida mas a conta não tem acesso a este modelo. Confirme que o nome do modelo está escrito exatamente como topaz-upscale/video.
O serviço não consegue obter seu vídeo
Esta é a falha mais comum. Sintoma: a tarefa falha cedo com erro de download ou de entrada. Causas:
- A URL é privada ou exige login interativo.
- A URL assinada expira antes de a tarefa chegar à etapa de download — especialmente provável em filas longas.
- O host bloqueia requisições automatizadas ou é lento demais, causando timeout.
Correção: envie o arquivo pela plataforma e referencie o identificador retornado, ou gere uma URL assinada com validade folgada no momento do envio.
Falha de decodificação
Se o erro mencionar a mídia e não a requisição, remuxe a origem para um contêiner comum e tente novamente. Teste o arquivo localmente primeiro — se até seu próprio player tem dificuldade, o serviço também terá.
A tarefa continua executando ou dá timeout
Origens longas levam muito tempo, e algumas requisições demoram desproporcionalmente. Antes de reenviar, verifique o status da tarefa pelo id — você pode estar vendo uma tarefa enfileirada, não uma tarefa com falha. Reenviar às cegas pode dobrar o custo. Se estiver consultando a partir de um script, garanta que o timeout do seu próprio cliente seja maior que a duração esperada da tarefa, caso contrário você abandonará uma tarefa que ainda está executando normalmente.
A saída parece pior que a origem
A requisição teve sucesso, mas o resultado está supernitidizado, com aparência plástica ou com fantasmas. É um problema de prompt, não da API: volte às receitas de reconstrução de detalhes e interpolação, adicione limites explícitos — "consistente com a origem", "sem fantasmas", "o fundo deve permanecer estático". Depois execute novamente seu conjunto padrão de comparação.
Falhas intermitentes e não reproduzíveis
Registre o corpo completo da requisição e o id da tarefa juntos a cada chamada. Sem os dois, você não consegue distinguir se a falha veio de um payload diferente ou de um problema temporário do serviço. Com uma dúzia de falhas registradas, o padrão costuma surgir em poucos minutos.
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