Como usar grok-imagine-1.5/image-to-video através da API hiapi: curl, Python e uma requisição pronta para executar

Resumo rápido

• O que é: Um guia copiável sobre como animar uma imagem estática em um vídeo curto usando grok-imagine-1.5/image-to-video através da API de tarefas unificada da hiapi.
• Fluxo: Crie a tarefa via POST /v1/tasks, faça polling em GET /v1/tasks/<taskId> (ou registre um callback) e então baixe o MP4 de data.output[0].url antes que expire.
• Schema de entrada (validado contra a API em produção): Aceita apenas uma entrada em image_urls, prompt opcional, duration de 1 a 15 segundos, resolution como 480p/720p, aspect_ratio como um de auto, 1:1, 16:9, 9:16, 3:2, 2:3. Nenhum outro campo é aceito.

O que você vai construir e o que precisa preparar

Objetivo: enviar uma imagem de origem mais um prompt de movimento e obter um clipe MP4 curto gerado pelo Grok Imagine 1.5.

Pré-requisitos:

• Uma chave de API hiapi — crie no painel. A chave tem o formato sk-... e vai no cabeçalho Authorization: Bearer.
• Uma URL de imagem de origem publicamente acessível (JPEG/PNG). A API busca a imagem no lado do servidor, então links localhost ou arquivos que exigem autenticação não funcionam.
• Qualquer cliente HTTP. Os exemplos abaixo usam curl e requests do Python.

O id do modelo é a string simples grok-imagine-1.5/image-to-video, sem sufixo.

Exemplo mínimo executável: curl

Criar a tarefa:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
      "image_urls": ["https://example.com/product-shot.jpg"],
      "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
      "duration": 6,
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'

O envio bem-sucedido retorna 200 e um taskId:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5", "status": "queued" },
  "message": "success"
}

Faça polling até a tarefa atingir um estado terminal (status passa por queued → handling → success ou fail):

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5" \
  -H "Authorization: Bearer sk-YOUR_KEY"

Tarefa concluída (resposta real, truncada):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01KWVVSTX0TJ32AD45F6ZQ08W5",
    "model": "grok-imagine-1.5/image-to-video",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "video",
        "url": "https://temp.hiapi.ai/.../01KWVVSTX0TJ32AD45F6ZQ08W5-0.mp4",
        "expireAt": 1783951451
      }
    ]
  },
  "message": "success"
}

⚠️ storage: "temp" e expireAt significam que a URL de download é temporária. Baixe o MP4 imediatamente após o sucesso da tarefa e armazene na sua própria infraestrutura — não faça hotlink.

Exemplo mínimo executável: Python

Script completo — criar, fazer polling, baixar:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Create the task
resp = requests.post(BASE, headers=HEADERS, json={
    "model": "grok-imagine-1.5/image-to-video",
    "input": {
        "image_urls": ["https://example.com/product-shot.jpg"],
        "prompt": "slow cinematic push-in, soft studio light drifting across the subject",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll for the result (image-to-video usually lands well within a few minutes)
deadline = time.time() + 600
while time.time() < deadline:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
    status = task["status"]
    if status == "success":
        break
    if status == "fail":
        raise RuntimeError(f"generation failed: {task.get('error')}")
    time.sleep(5)
else:
    raise TimeoutError(f"task {task_id} still not finished after 10 min")

# 3. Download immediately — the output URL expires
video_url = task["output"][0]["url"]
mp4 = requests.get(video_url, timeout=120)
mp4.raise_for_status()
with open("clip.mp4", "wb") as f:
    f.write(mp4.content)
print("saved clip.mp4,", len(mp4.content), "bytes")

Referência de entrada (o que o schema realmente aceita)

Estas restrições vêm diretamente do validador em produção, não são suposições — enviar qualquer outra coisa retorna 400 INVALID_REQUEST com uma mensagem precisa:

Campo	Tipo	Regra
image_urls	array de strings	Obrigatório, exatamente 1 URL (maxItems: 1)
prompt	string	Opcional — descreve movimento, movimento de câmera e clima
duration	inteiro	1–15 segundos
resolution	string	480p ou 720p
aspect_ratio	string	auto, 1:1, 16:9, 9:16, 3:2, 2:3

Notas:

• Este modelo não tem os campos seed, negative_prompt, fps, motion_strength ou camera_fixed. O schema rejeita propriedades desconhecidas (additional properties ... not allowed), então controle movimento e comportamento de câmera inteiramente através do prompt.
• Cada tarefa só pode ter uma imagem de referência. Passar duas retorna image_urls: maxItems: got 2, want 1.
• aspect_ratio: "auto" segue a proporção da própria imagem de origem — que geralmente é o desejado para imagens de produto.
• O modelo mais antigo grok-imagine/image-to-video aceita até 30 segundos por clipe; o 1.5 tem limite de 15 segundos. Ambos têm o mesmo preço por segundo: $0.015 para 480p e $0.0282 para 720p.

Considerações para produção

Use callbacks em vez de polling. Para qualquer cenário além de scripts, registre um webhook ao criar a tarefa e pule o loop de polling:

{
  "model": "grok-imagine-1.5/image-to-video",
  "input": { "image_urls": ["https://example.com/shot.jpg"], "duration": 6 },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

callback.url deve ser um endpoint http(s) público, e when aceita apenas "final" — você recebe um POST quando a tarefa atinge success ou fail. Polling serve para CLI e tarefas em lote; callbacks são superiores quando você precisa gerar muitos clipes em massa sem querer implantar um exército de pollers. Mantenha um polling de fallback (por exemplo, verificar a cada poucos minutos tarefas que não receberam callback) para que um webhook perdido não deixe tarefas presas.

Idempotência. A criação de tarefas não é deduplicada no servidor, então uma simples retentativa após um timeout de rede pode causar envios duplicados e cobrança duplicada. Persista o taskId imediatamente após o retorno da chamada de criação e verifique seu próprio armazenamento antes de retentar; se você travar entre o envio e a persistência, liste as tarefas recentes (GET /v1/tasks) e corresponda por modelo + horário de criação antes de reenviar.

Tratamento de erros. Os modos de falha que você realmente vai encontrar:

• 401 com {"error": {"code": "permission_denied", "type": "hiapi_error", ...}} — chave errada ou chave sem acesso ao modelo. A resposta inclui um request_id para suporte.
• 400 com error_code: "INVALID_REQUEST" — violação de schema; a message indica o campo e a regra específicos (por exemplo, duration: maximum: got 99, want 15). Corrija o corpo da requisição, não retente cegamente.
• 402 saldo insuficiente — modelos de vídeo fazem uma pré-checagem da sua cota no momento do envio. Recarregue e reenvie.
• A própria tarefa com status: "fail" — falha do lado da geração; verifique data.error e retente com backoff. Imagem de origem inacessível é uma causa comum.

Armazene a saída imediatamente. Vale repetir: output[0].url fica em armazenamento temporário, com um timestamp expireAt. No momento em que você vê success, transfira o MP4 imediatamente para o seu próprio bucket. Se o seu pipeline travar após o sucesso e antes do download, busque a tarefa novamente por id — a URL permanece válida até expireAt, não para sempre.

Leitura relacionada

• Página do modelo grok-imagine-1.5/image-to-video — preços, parâmetros e playground no navegador
• Como usar grok-imagine/image-to-video — modelo anterior, mesmo fluxo de tarefas, limite de 30 segundos
• Guia de texto para vídeo do Grok Imagine — comece a partir de um prompt em vez de uma imagem
• Referência da API hiapi — contrato completo da API de tarefas

Perguntas frequentes

Qual o comprimento máximo dos vídeos do grok-imagine-1.5? De 1 a 15 segundos, definido pelo campo inteiro duration. Solicitar mais retorna 400 (duration: maximum: got X, want 15). Se precisar de até 30 segundos, use o modelo mais antigo grok-imagine/image-to-video.

Quais resoluções e proporções de tela ele suporta? resolution é 480p ou 720p; aspect_ratio é auto, 1:1, 16:9, 9:16, 3:2 ou 2:3. 9:16 com 720p é a combinação preferida para clipes verticais no estilo Shorts/Reels.

Posso passar múltiplas imagens de referência? Não — o image_urls deste modelo aceita exatamente uma URL. Para fluxos com múltiplas referências, encadeie tarefas ou combine as imagens de referência em uma única imagem de entrada primeiro.

Há seed ou prompt negativo? Não. O schema de entrada rejeita diretamente seed, negative_prompt, fps e campos similares. Estilo de movimento, movimento de câmera e clima são controlados inteiramente pela string prompt.

Quanto custa? Cobrado por segundo de vídeo gerado: $0.015/segundo para 480p e $0.0282/segundo para 720p. Um clipe de 6 segundos custa $0.09 em 480p e $0.1692 em 720p. Se duration não for enviado, o padrão é 8 segundos. Mais exemplos em Detalhamento de preços do Grok Imagine 1.5.

Por que minha requisição retorna 401 permission_denied? Ou a chave de API está errada/revogada, ou ela não tem acesso ao modelo. Verifique a chave no painel e certifique-se de enviar Authorization: Bearer sk-... — a falta do prefixo Bearer produz o mesmo erro.

Como saber que o vídeo está pronto sem fazer polling? Anexe "callback": {"url": "https://your-endpoint", "when": "final"} ao criar a tarefa. Quando a tarefa atinge um estado terminal, a hiapi envia um POST para o seu endpoint. Como fallback, faça polling em GET /v1/tasks/<taskId>.

Por que a URL do meu vídeo para de funcionar depois de alguns dias? A saída fica em armazenamento temporário — cada entrada de saída tem um timestamp expireAt. Baixe o arquivo imediatamente após o success e sirva a partir do seu próprio armazenamento.