Blogue

Tutorial

Como usar o pixverse-v6-max de imagem para vídeo via API HiAPI: curl, Python e uma requisição que funciona

Nov 13, 2026
Capa em estilo editorial plano: sobre um fundo verde-pinho-escuro, um grande prisma é dividido em blocos de cor verde-sálvia e verde-neblina.
Nesta página

O que o endpoint pixverse-v6-max de imagem para vídeo exige

O endpoint pixverse-v6-max/image-to-video na HiAPI é uma tarefa assíncrona de geração de vídeo condicionada por imagem. Essa única frase praticamente determina todas as decisões que você toma ao integrá-lo.

O endpoint recebe uma imagem de origem (o primeiro quadro) mais um conjunto de parâmetros de geração e retorna uma referência de tarefa, não o vídeo finalizado. A renderização real acontece no servidor e, dependendo dos parâmetros escolhidos, pode levar de alguns segundos a vários minutos. Seu cliente é responsável por enviar a tarefa e depois consultar seu status repetidamente até que ela reporte um estado terminal.

Compare isso com a edição síncrona de imagens: na edição síncrona, você faz um POST de um corpo de requisição e recebe a imagem transformada na mesma resposta HTTP. Aqui o fluxo é:

  1. Faça POST da sua imagem e parâmetros para o endpoint de geração.
  2. Receba um identificador de tarefa (geralmente junto com um status inicial).
  3. Faça GET do status da tarefa em intervalos até que ela conclua ou falhe.
  4. Leia a URL do vídeo gerado a partir do corpo da resposta da tarefa concluída.

Por causa dessa separação, existem duas classes distintas de erros: problemas na fase de envio (erros de autenticação, corpo de requisição malformado, imagem rejeitada) e problemas na fase de execução (a tarefa foi aceita, mas falha ou estagna). Uma boa integração trata ambos explicitamente — veja o checklist concreto na seção de solução de problemas mais adiante.

Mais uma coisa a ter em mente: a imagem de origem é a âncora. O modelo anima a partir desse primeiro quadro, então a qualidade, a proporção e o conteúdo da imagem influenciam a saída mais do que qualquer texto de prompt que você forneça. Trate a correção do upload como a principal preocupação, não como algo secundário.

Prepare sua chave de API e o endpoint

Antes de fazer a primeira requisição, você só precisa de duas coisas: uma chave de API da HiAPI e a URL base correta do endpoint.

Obtenha sua chave

Crie uma chave de API no console da sua conta HiAPI. Trate-a como uma senha: mantenha-a em uma variável de ambiente, não no código-fonte nem no histórico do shell.

export HIAPI_API_KEY="your_key_here"

Se você usa um arquivo .env localmente, adicione-o ao .gitignore antes de enviar qualquer coisa. Qualquer chave que apareça em logs compartilhados, capturas de tela ou repositórios de código deve ser rotacionada imediatamente.

Conheça sua URL base e o caminho

O endpoint fica sob o host da API HiAPI, com o caminho do modelo pixverse-v6-max/image-to-video. Nos exemplos abaixo, a URL base aparece como https://api.hiapi.ai e o caminho completo é construído a partir dela. Se sua conta ou região fornecer um host diferente, substitua-o de forma consistente — uma incompatibilidade entre host e chave é uma das causas mais comuns de 401, e os desenvolvedores frequentemente assumem erroneamente que se trata de uma "chave inválida".

Escolha sua ferramenta

  • curl para uma primeira verificação rápida — ele elimina todas as variáveis além da própria requisição.
  • Python 3 com requests (ou httpx) para a integração real.
python3 -c "import requests; print(requests.__version__)"

Se ele imprimir um número de versão, você está pronto. Os exemplos deste artigo não exigem instalar um SDK; tudo é HTTP puro, o que também significa que você pode portá-lo para qualquer linguagem depois. Assim que a chave e o host estiverem confirmados, você pode começar a construir a requisição.

Construa a requisição com curl

Comece com a menor requisição que realmente funcione e só então adicione parâmetros. O corpo abaixo mostra a estrutura de um envio completo de imagem para vídeo.

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://your-cdn.example.com/first-frame.jpg",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

Três coisas acontecem aqui:

  • A autenticação é feita por meio de um bearer token no cabeçalho Authorization.
  • O corpo é JSON, então a imagem é fornecida como uma string de URL (veja a próxima seção para saber como enviar um arquivo local).
  • Dois parâmetros de geração — duration e aspect_ratio — são campos de nível superior.

Um envio bem-sucedido retorna um objeto JSON contendo um identificador de tarefa. Capture-o:

JOB_ID=$(curl -s -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"https://your-cdn.example.com/first-frame.jpg","duration":5,"aspect_ratio":"16:9"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
echo "$JOB_ID"

Depois, consulte-o:

curl -s "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Em caso de falha, sempre verifique o campo de status e o corpo bruto da resposta de erro. O curl ainda pode imprimir JSON de erro com código de saída 0, então em scripts não dependa apenas do código de saída.

Forneça a imagem do primeiro quadro corretamente

A imagem de origem é o ponto de falha mais comum; quase toda rejeição se resume a uma destas quatro causas.

1. A imagem não está acessível

Quando você passa uma URL, os servidores da HiAPI precisam conseguir fazer GET dela — a partir da rede deles, não da sua. Uma URL localhost, um bucket privado, uma URL assinada que expira em sessenta segundos ou um endpoint atrás de VPN vão falhar. Use uma URL de armazenamento de objetos publicamente legível ou um link de CDN e confirme que ela carrega em uma sessão de navegador nova, sem cookies.

2. Formato de imagem não suportado

Fique com formatos web padrão — JPEG, PNG, WebP. Arquivos com extensões incomuns, HEIC de celular ou GIFs animados são arriscados. Se seu pipeline gera algum formato exótico, faça transcodificação primeiro.

3. O primeiro quadro não corresponde à proporção declarada

Isso é sutil. Se sua imagem de origem é quadrada, mas você solicita 16:9, o serviço terá que cortar, preencher ou rejeitar a entrada. O comportamento pode variar, e nenhuma das três opções é o que a maioria dos desenvolvedores quer. Recorte ou adicione barras pretas antes do upload, de modo que a geometria da imagem já corresponda ao aspect_ratio que você vai solicitar. Isso torna a saída previsível e evita desperdiçar uma tarefa.

4. Imagem grande ou pequena demais

Imagens estáticas de altíssima resolução (por exemplo, saída de câmera 8K) consomem largura de banda e podem ser rejeitadas ou reduzidas; miniaturas minúsculas deixam o modelo com quase nada para animar. Normalize a imagem para um tamanho de lado maior razoável como parte da etapa de pré-upload.

Enviar um arquivo local

Se o endpoint aceitar upload multipart para o campo de imagem, o padrão é:

curl -X POST "https://api.hiapi.ai/v1/pixverse-v6-max/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -F "image=@./first-frame.jpg" \
  -F "duration=5" \
  -F "aspect_ratio=16:9"

Observe que, com multipart, campos numéricos se tornam strings. Consulte a documentação de referência do endpoint para saber quais tipos de conteúdo são aceitos e, em pipelines de produção, prefira a forma de URL — assim os arquivos binários grandes nem passam pelo seu servidor de aplicação.

Defina duração e proporção

Esses dois campos têm mais impacto no custo e na saída do que qualquer outra coisa no corpo da requisição.

duration

duration está em segundos e indica o comprimento do clipe gerado. É também o campo mais diretamente relacionado à cobrança — o preço em tempo real é calculado com base na duração de saída solicitada, então escolha com cuidado em vez de usar o máximo por padrão. Dicas práticas:

  • Comece com a duração mais curta que conte sua história. Clipes de 5 segundos são ótimos para loops, teasers de produto ou ganchos para redes sociais.
  • Use durações mais longas apenas quando a cena realmente precisar de mais tempo; um primeiro quadro estático animado por muito tempo tende a derivar e perder coerência.
  • Valide no cliente: antes que a requisição saia do seu serviço, rejeite valores não inteiros, zero, negativos e valores absurdamente grandes.
if not isinstance(duration, int) or not 1 <= duration <= 8:
    raise ValueError("duration out of supported range")

Confirme o intervalo suportado atual na documentação de referência do endpoint e reflita-o na sua lógica de validação — não codifique as suposições deste artigo de forma fixa.

aspect_ratio

aspect_ratio é uma string, como "16:9", "9:16" ou "1:1". Ela controla a geometria do quadro de saída.

  • 16:9 para paisagem: YouTube, vídeos de destaque na web, reprodução no desktop.
  • 9:16 para retrato: Reels, Shorts, veiculação estilo TikTok.
  • 1:1 para feeds e miniaturas.

Duas regras evitam problemas. Primeiro, faça a imagem de origem corresponder à proporção solicitada — um primeiro quadro retrato em uma requisição paisagem causará um corte que você provavelmente não quer. Segundo, trate a proporção como um enum, não como texto livre: valide contra uma lista permitida, para que erros de digitação como "16x9" falhem rapidamente no seu código, em vez de falharem após uma ida e volta.

Todo o resto

Se o endpoint expuser controles de geração adicionais, deixe-os fora da sua primeira requisição. Um corpo mínimo e validado é sua linha de base; adicione um parâmetro por vez e compare as saídas. Essa disciplina torna óbvio qual campo causou uma regressão.

Implemente a mesma requisição em Python

Abaixo está a tradução do fluxo curl para Python. Ele mantém as dependências deliberadamente enxutas: requests mais a biblioteca padrão.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def submit(image_url: str, duration: int = 5, aspect_ratio: str = "16:9") -> str:
    resp = requests.post(
        f"{BASE}/v1/pixverse-v6-max/image-to-video",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": image_url, "duration": duration, "aspect_ratio": aspect_ratio},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]

def fetch(job_id: str) -> dict:
    resp = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    job_id = submit("https://your-cdn.example.com/first-frame.jpg")
    print("submitted", job_id)

Algumas escolhas deliberadas que vale a pena adotar:

  • raise_for_status() no envio. Um 400 ou 401 deve aparecer imediatamente como exceção, em vez de virar um KeyError quando você tenta ler ["id"] do corpo da resposta de erro.
  • Timeouts explícitos. Sem timeout, uma conexão travada deixa seu worker pendurado indefinidamente.
  • Configuração lida do ambiente. A URL base e a chave nunca são codificadas fixamente no código.
  • Funções auxiliares pequenas e tipadas. submit retorna a string do id da tarefa; fetch retorna um dicionário. Centralizar o parsing em um lugar significa que uma mudança de esquema exige apenas uma linha.

Se você preferir httpx, basta substituir por httpx.post(...) e httpx.get(...); as chamadas são idênticas em todos os outros aspectos. Para qualquer coisa executada dentro de um manipulador de requisições web, envie a tarefa aqui e passe o id da tarefa para um worker em segundo plano, em vez de bloquear a requisição HTTP do usuário na geração do vídeo.

Consulte a tarefa assíncrona até a conclusão

A consulta periódica é a parte que a maioria dos tutoriais passa por cima e também a origem da maioria dos incidentes. O loop em si é curto; a disciplina ao redor dele é o que importa.

def wait_for_video(job_id: str, timeout: int = 600, interval: int = 5) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        job = fetch(job_id)
        status = job.get("status")
        if status == "completed":
            return job["output"]["video_url"]
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {job.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish within {timeout}s")

Os pontos codificados acima:

  • Sempre defina um prazo final. A geração de vídeo é lenta; um loop sem limite se torna cobrança sem limite e workers travados. Dez minutos é um teto razoável para clipes curtos — ajuste-o conforme sua configuração de duração.
  • Distinga estados terminais. Apenas completed produz uma URL. failed e cancelled também são terminais — pare de consultar e exponha o campo de erro.
  • Use um intervalo razoável. A cada poucos segundos já é suficiente. Martelar o endpoint de status fará você ser limitado por taxa e não dirá nada de novo.
  • Recuo suave para tarefas longas: aumente o intervalo de 3 para 10 segundos após o primeiro minuto. Isso reduz a carga sem acrescentar custo de latência para você.
  • Persista o id da tarefa. Armazene-o junto com seus próprios registros, para que, se o processo reiniciar, você possa retomar a consulta sem reenviar — e pagar novamente — a mesma tarefa.
  • Nunca consulte diretamente do navegador com sua chave de API. Faça a verificação de status por meio de um proxy no seu backend.

Quando a tarefa terminar, baixe o vídeo prontamente para o seu próprio armazenamento, em vez de vincular para sempre à URL retornada; URLs de ativos gerados não têm garantia de permanência.

Diagnostique tarefas com falha e estagnadas

Siga este checklist em ordem. Cada etapa isola uma camada.

Erros de envio (a tarefa nunca foi criada)

  • 401 Unauthorized — chave ausente, mal formatada, revogada ou combinada com o host errado. Verifique se o cabeçalho é exatamente Authorization: Bearer <key>, com um único espaço no meio, e se a variável de ambiente não tem quebras de linha extras.
  • 403 Forbidden — a chave é válida, mas não tem permissão para este modelo ou endpoint. Verifique o caminho do recurso caractere por caractere: pixverse-v6-max/image-to-video.
  • 400 Bad Request — seu JSON está malformado ou algum campo é inválido. Decodifique o corpo da resposta de erro; ele normalmente indica o campo problemático. Culpados comuns: duration como string em vez de número, "16x9" em vez de "16:9", ausência de image.
  • Erro de validação do tipo 422 — o campo existe, mas está fora do intervalo. Consulte a documentação de referência do endpoint, em vez de adivinhar.
  • 429 Too Many Requests — você está enviando rápido demais. Enfileire os envios e repita com recuo exponencial com jitter; nunca repita em loop apertado.

Falhas de execução (a tarefa foi criada, mas não teve sucesso)

  • Status failed com um erro relacionado à imagem — a busca da URL de origem falhou após o envio. Esta é a clássica armadilha do "funciona no meu navegador": a URL exige cookie, referrer ou lista de IPs permitidos. Realoque a imagem publicamente.
  • Status failed com um erro de conteúdo ou validação — a imagem de origem foi rejeitada por motivos técnicos (formato, geometria, tamanho). Transcodifique, redimensione e recorte novamente para a proporção declarada.
  • Tarefa presa em fila ou em processamento após seu prazo final — primeiro confirme que você está lendo o id de tarefa correto (erros de copiar e colar são surpreendentemente comuns). Depois verifique se o status realmente não mudou ou se sua consulta está indo para a URL base errada. Se ela realmente estagnou, cancele e reenvie uma vez, se a API permitir; reenviar silenciosamente várias vezes é exatamente como o orçamento desaparece.

Um hábito que economiza tempo

Registre o id completo da requisição, o id da tarefa, o status HTTP e o corpo da resposta para cada chamada — e mascare a chave. Quando algo der errado às duas da manhã, um id de requisição é a diferença entre cinco minutos de correção e uma hora de adivinhação. Comece com o corpo mínimo e validado, adicione um parâmetro por vez, e você quase nunca precisará deste checklist.

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