Blogue

Tutorial

Como usar topaz-upscale/video pela API HiAPI: exemplos em curl e Python

Nov 17, 2026
Imagem de capa: várias lâminas de vidro translúcido sobrepostas em ângulos contidos, refratando faixas de cor azul-frio paralelas sobre um fundo claro, sem texto na imagem.
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:

  1. 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.
  2. 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.
  3. 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/video cobre 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:

  1. Fácil — bem iluminado, movimento lento, origem limpa. Deve parecer quase perfeito; se não, algo está configurado errado.
  2. Difícil — movimento rápido, detalhes finos ou tipos de movimento mistos. Artefatos de interpolação aparecerão aqui.
  3. 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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API