Como usar a API Grok Imagine para texto para vídeo: curl, Python e uma requisição funcional

Grok Imagine é o modelo de geração de vídeo da xAI, e o HiAPI expõe sua variante de texto para vídeo no mesmo endpoint assíncrono unificado usado por todos os outros modelos de geração: POST /v1/tasks. Você envia um prompt (mais duração, modo, proporção e resolução opcionais), recebe imediatamente um taskId e obtém uma URL .mp4 quando a tarefa termina.

Este guia é o caminho mais curto até uma requisição funcional: o esquema de entrada exato (validado contra a API em produção, incluindo o erro 400 que você recebe ao adivinhar errado um nome de campo), o fluxo curl pronto para copiar e colar, um pequeno cliente Python com polling e o padrão de callback que você usará em produção.

O que você vai construir e o que precisa

Objetivo: transformar prompts de texto em clipes de vídeo de 6 a 30 segundos usando grok-imagine/text-to-video, inteiramente via HTTP.

Você só precisa de uma coisa: uma chave de API do HiAPI. Crie uma no painel do HiAPI — uma única chave funciona para todos os modelos, então se você já chama modelos de imagem no HiAPI, a mesma chave serve aqui. As requisições se autenticam com um cabeçalho bearer padrão:

Authorization: Bearer sk-<your-key>

O esquema de entrada (antes de escrever qualquer código)

A API de tarefas valida input estritamente por modelo — campos desconhecidos são rejeitados com 400 em vez de silenciosamente ignorados. Aqui está o esquema completo de grok-imagine/text-to-video:

Campo	Tipo	Obrigatório	Valores	Padrão
prompt	string	sim	até 5000 caracteres; inglês funciona melhor	—
duration	integer	não	6–30 (segundos)	6
mode	enum	não	fun, normal	normal
aspect_ratio	enum	não	2:3, 3:2, 1:1, 16:9, 9:16	2:3
resolution	enum	não	480p, 720p	480p

Três coisas vale saber de antemão:

• mode é o botão de "modo de movimento". normal é equilibrado; fun produz movimento mais criativo e exagerado. Se você viu os modos do Grok Imagine descritos com outros nomes em outro lugar, o parâmetro da API é mode — enviar algo como motion_mode resulta em 400 additional properties 'motion_mode' not allowed.
• duration afeta o custo linearmente. O Grok Imagine cobra por segundo de saída, então um clipe de 30 segundos custa 5 vezes mais que um de 6 segundos. Veja a tarifa atual por segundo na página de preços do HiAPI.
• A proporção padrão é 2:3 (retrato). Se você quer widescreen, passe 16:9 explicitamente — isso pega de surpresa quem migra de modelos cujo padrão é horizontal.

Valores fora do intervalo falham rapidamente com uma mensagem descritiva, por exemplo duration: 31 retorna:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: duration: maximum: got 31, want 30"}

Exemplo mínimo funcional: curl

Duas chamadas: criar a tarefa e depois consultá-la.

1. Crie a tarefa:

export HIAPI_API_KEY="sk-..."

curl -sS -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-video",
    "input": {
      "prompt": "A red fox trotting through fresh snow at dawn, low golden light, cinematic tracking shot",
      "duration": 6,
      "mode": "normal",
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Note que o id do modelo é a string nua grok-imagine/text-to-video — sem prefixo de provedor e sem sufixo de versão.

2. Consulte até o estado terminal:

TASK_ID="tk-hiapi-..."

curl -sS "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"
# while .data.status is "handling", sleep a few seconds and retry.
# On success:
# {
#   "code": 200,
#   "data": {
#     "status": "success",
#     "model": "grok-imagine/text-to-video",
#     "output": [
#       {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4", "expireAt": 1783300000}
#     ],
#     ...
#   }
# }

A URL .mp4 é temporária — expireAt é um timestamp Unix cerca de uma semana no futuro. Baixe os bytes e persista por conta própria logo após a tarefa ter sucesso; não faça hotlink de URLs temp.hiapi.ai em nenhum lugar voltado ao usuário. (Se você já encontrou um link de saída expirado, a causa está aqui — veja URL de saída do hiapi expirada: baixe antes que expire.)

Python: um pequeno cliente de polling

Um script reutilizável para o mesmo fluxo — criar, consultar com prazo e baixar:

# pip install requests
import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task(prompt: str, duration: int = 6, mode: str = "normal",
                aspect_ratio: str = "16:9", resolution: str = "720p") -> str:
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "grok-imagine/text-to-video",
        "input": {
            "prompt": prompt,
            "duration": duration,          # 6-30, billed per second
            "mode": mode,                  # "normal" | "fun"
            "aspect_ratio": aspect_ratio,  # "2:3" | "3:2" | "1:1" | "16:9" | "9:16"
            "resolution": resolution,      # "480p" | "720p"
        },
    }, timeout=60)
    data = resp.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id


def wait_task(task_id: str, timeout_s: int = 900, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} not done after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_task(
        "A red fox trotting through fresh snow at dawn, low golden light, "
        "cinematic tracking shot",
        duration=6,
    )
    print("task:", task_id)
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    video = requests.get(url, timeout=120).content   # expires — persist now
    with open("fox.mp4", "wb") as f:
        f.write(video)
    print(f"saved fox.mp4 ({len(video)} bytes)")

Clipes de 6 segundos normalmente terminam muito antes do prazo de 15 minutos acima; durações mais longas levam mais tempo proporcionalmente, então mantenha esse timeout folgado para tarefas de 30 segundos.

Considerações para produção

Use callbacks em vez de polling. Para qualquer coisa além de scripts, passe um objeto callback de nível superior na criação, e o HiAPI enviará por POST o estado terminal da tarefa ao seu endpoint — sem loop de polling para monitorar:

{
  "model": "grok-imagine/text-to-video",
  "input": {"prompt": "...", "duration": 12},
  "callback": {"url": "https://your-domain.com/hiapi/callback", "when": "final"}
}

when aceita apenas "final" (você recebe um POST quando a tarefa atinge success ou fail, não progresso incremental). Regra geral: polling é bom para CLIs, jobs em lote e qualquer cenário de vida curta; callbacks são bons para backends web, onde de outra forma você ocuparia a capacidade de workers com renderizações de vários minutos. Se seu endpoint de callback parece não receber nada, investigue por que seu callback de tarefa do hiapi não dispara.

Idempotência. A criação de tarefas não é idempotente — repetir uma requisição de criação que deu timeout pode gerar duas tarefas cobradas. Registre o taskId no momento em que o receber e, em caso de falha ambígua (timeout de rede na criação), verifique seu histórico de tarefas antes de reenviar. Como duration é cobrado por segundo, uma tarefa duplicada de 30 segundos é o tipo caro de duplicação.

Tratamento de erros. Os dois tipos de erro que você realmente verá:

• Erros 400 de esquema (error_code: "INVALID_REQUEST") — nome de campo errado, duração fora do intervalo, valor de enum inválido. São determinísticos; corrija a requisição, não tente novamente.
• Falhas de autenticação — uma chave inválida ou uma chave sem acesso a este modelo retorna 401 com "code": "permission_denied" e a mensagem "This API key cannot use the selected model." Verifique a chave no painel e confirme que o modelo está habilitado para ela.
• Falhas no nível da tarefa — a criação teve sucesso, mas a tarefa termina posteriormente com status: "fail" e um objeto error (política de conteúdo, capacidade upstream). Vale tentar de novo uma vez com backoff. Se uma tarefa parecer travada em handling, veja diagnosticando jobs /v1/tasks travados ou com timeout.

Próximos passos

• Página do modelo Grok Imagine texto para vídeo — playground e preços atuais
• Referência de entrada do modelo — o esquema canônico deste modelo
• Criar tarefa e obter detalhes da tarefa — o envelope completo da API assíncrona
• Início rápido — faça sua primeira chamada ao HiAPI de ponta a ponta, e autenticação para o tratamento de chaves

Perguntas frequentes

O que é a API Grok Imagine e como acesso? Grok Imagine é o modelo de geração de vídeo da xAI. Via HiAPI, você o chama como grok-imagine/text-to-video no endpoint unificado POST /v1/tasks usando uma única chave de API do HiAPI — sem conta ou SDK separados da xAI.

Qual é a duração máxima de um vídeo do Grok Imagine? duration aceita números inteiros de 6 a 30 segundos (padrão 6). Valores fora desse intervalo são rejeitados na criação com 400, e a cobrança é por segundo de saída.

Qual é a diferença entre os modos fun e normal? normal (padrão) oferece movimento equilibrado e realista; fun tende ao criativo e ao exagerado. Este é o único botão de estilo de movimento exposto pela API — escolhido por requisição, não por conta.

grok-imagine/text-to-video suporta 1080p? Atualmente não — resolution aceita 480p (padrão) ou 720p. Se você precisa de resolução de saída maior, faça upscale downstream ou compare outros modelos de vídeo na página de modelos.

Posso usar o Grok Imagine para animar uma imagem existente? Com este modelo não — ele é somente texto. Existe um modelo separado grok-imagine/image-to-video no mesmo endpoint de tarefas que aceita entrada de imagem; o ciclo de vida assíncrono (criar → consultar/callback → baixar) é idêntico.

A API Grok Imagine tem nível gratuito? A geração é cobrada do seu saldo do HiAPI por segundo de vídeo — não há endpoint gratuito sem chave. Veja as tarifas atuais na página de preços; para saber como "grátis" realmente se parece nesse espaço, esta comparação de APIs de texto para vídeo gratuitas cobre as opções.