Como usar a API Creatify Boreal: gerar vídeos a partir de texto, imagem e áudio

creatify-boreal é um modelo de vídeo no hiapi que retorna um clipe finalizado com voz e som já mixados. Um único id de modelo cobre três pontos de partida: apenas prompt, prompt com imagem de referência, ou prompt com seu próprio áudio de narração. Este guia mostra a requisição, o loop de polling e o resultado de uma geração real que executei.

Você precisa obter uma chave de API no painel do hiapi. Todas as chamadas passam pelo endpoint unificado de tarefas POST /v1/tasks.

Campos de entrada

Estes campos foram conferidos com a página do modelo ao vivo e validados enviando valores propositalmente inválidos para /v1/tasks; valores inválidos retornam 400 e não são cobrados.

Campo	Obrigatório	Valores aceitos
prompt	Sim	Texto, até 5000 caracteres
image_url	Não	JPG/PNG/WebP, 10 MB; define o sujeito e a composição
audio_url	Não	MP3/WAV/M4A, 15 MB; usa apenas os primeiros duration segundos
negative_prompt	Não	Até 2000 caracteres
resolution	Não	720p, 1080p, 2k
aspect_ratio	Não	auto, 16:9, 9:16, 1:1, 4:3, 3:4
duration	Não	Segundos inteiros, de 1 a 20

Esses três modos não são ids de modelo separados. Para texto para vídeo, omita image_url e audio_url; para imagem para vídeo, adicione image_url; adicione audio_url (normalmente junto com uma imagem) para que o apresentador siga sua narração.

Requisição mínima funcional

curl -X POST 'https://api.hiapi.ai/v1/tasks' \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "creatify-boreal",
    "input": {
      "prompt": "Vídeo UGC em estilo selfie vertical: uma jovem em um quarto iluminado levanta um batom rosa suave na direção da câmera e diz: \"Tá bom, esse é o único batom que sobreviveu ao meu inverno.\" Som ambiente natural do quarto.",
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "duration": 4
    }
  }'

A resposta fornece o id da tarefa:

{"code":200,"data":{"taskId":"tk-hiapi-01M5MJC8NG8E1E0XN9NEJRDBQH"},"message":"success"}

Python: enviar e fazer polling

import os, time, requests

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

def create(payload: dict) -> str:
    r = requests.post(BASE, headers=HEADERS, json=payload, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id: str, every: int = 10, limit: int = 900) -> dict:
    start = time.time()
    while time.time() - start < limit:
        try:
            d = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except (requests.RequestException, ValueError):
            time.sleep(every)  # erro de rede transitório: continue consultando o mesmo id
            continue
        if d["status"] == "success":
            return d
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

task_id = create({
    "model": "creatify-boreal",
    "input": {
        "prompt": "Vídeo UGC em estilo selfie vertical: uma jovem levanta um batom rosa suave na direção da câmera e diz: \"Tá bom, esse é o único batom que sobreviveu ao meu inverno.\" Som ambiente natural do quarto.",
        "resolution": "720p",
        "aspect_ratio": "9:16",
        "duration": 4,
    },
})
result = wait(task_id)
print(result["output"][0]["url"])

O status passa por handling, archiving e então success. A URL do vídeo fica em data.output[0].url.

Modos de imagem e áudio

Imagem para vídeo adiciona um campo a mais:

{"model": "creatify-boreal",
 "input": {"prompt": "Esta mulher sorri e fala para a câmera na cozinha: \"Troquei meu café por esta bebida de aveia com leite.\" Som ambiente natural da cozinha.",
           "image_url": "https://your-cdn.example/presenter.jpg",
           "resolution": "720p", "duration": 8}}

O modo conduzido por áudio adiciona um audio_url apontando para um arquivo de narração. A página do modelo descreve que a narração é mantida no vídeo, que os lábios acompanham a narração e que apenas os primeiros duration segundos do áudio são usados, então defina duration com o comprimento de clipe desejado. O exemplo de áudio na página do modelo combina áudio com uma imagem de referência; eu mesmo não executei uma geração de imagem mais áudio, portanto essa combinação é, neste artigo, documentada em vez de verificada.

Como é uma execução real

Executei a requisição acima (somente texto, 720p, 9:16, 4 segundos).

• Tempo de geração: a tarefa ficou cerca de 283 segundos em handling e depois cerca de 10 segundos em archiving. Mesmo para um clipe de 4 segundos, planeje em minutos, não em segundos. Faça polling a cada 10 segundos ou use callback, em vez de timeouts curtos.
• Arquivo de saída: MP4 de 720x1280, vídeo H.264 a 24 fps mais uma faixa de áudio AAC, duração de 4,04 segundos. Embora a requisição não tivesse campo de áudio, o áudio está presente, o que condiz com o design de som nativo do modelo.
• URL temporária: a URL de saída fica em temp.hiapi.ai, com um expireAt que expira em cerca de 7 dias. Baixe o arquivo e armazene-o você mesmo, em vez de linká-lo a partir da página.
• Formato do custo: cobrado por segundo e dependente de resolution (veja a página de preços), portanto a forma mais barata de iterar prompts é 720p com um duration curto, e depois renderizar novamente a versão final em 1080p ou 2k.

Armadilhas que encontrei

• Valores errados falham rápido e de graça. Enviar aspect_ratio: "7:5", duration: 25 ou resolution: "4k" retorna HTTP 400 INVALID_REQUEST, com uma mensagem que lista os valores permitidos ('auto', '16:9', '9:16', '1:1', '4:3', '3:4', máximo 20, e '720p', '1080p', '2k'). Use isso para validar seus próprios formulários antes de enviar.
• URLs de mídia erradas falham mais tarde, durante o polling. Enviei audio_url: "https://example.com/a.mp3" (que não era um arquivo de áudio real). A chamada de criação retornou HTTP 200 com um id de tarefa e, cerca de 15 segundos depois, a tarefa terminou com status: "fail" e error.code: "INVALID_REQUEST". Portanto, um 200 na criação não significa que sua mídia está disponível; sempre verifique o status final e leia data.error. Nesse caso, a falha aparece dentro de uma resposta de polling HTTP 200, e não como erro HTTP.
• Falha é status: "fail", não um status HTTP. A própria requisição de polling retorna 200, então verifique data.status.

Páginas relacionadas

• Página do modelo Creatify Boreal: Playground, preços ao vivo e clipes de exemplo
• Preços do hiapi
• Documentação do hiapi
• Como usar a API OmniHuman 1.5: outro modelo de vídeo com apresentador
• API Ray 3.2 de imagem para vídeo
• Guia da API de vídeo Wan 3.0

Perguntas frequentes

Entradas de texto, imagem e áudio exigem ids de modelo separados? Não. As três usam creatify-boreal; os campos que você inclui em input determinam o modo.

Qual é o comprimento máximo do clipe? Segundos inteiros de 1 a 20. O valor 25 é rejeitado com HTTP 400.

A saída inclui som? Sim. O clipe de teste de 4 segundos tem uma faixa de áudio AAC mesmo sem entrada de áudio fornecida.

Quais resoluções estão disponíveis? 720p, 1080p e 2k. A cobrança varia conforme a resolução; consulte a página de preços.

Quanto tempo devo esperar? Meu teste de 4 segundos em 720p levou cerca de cinco minutos de ponta a ponta. Use polling com um limite generoso ou callback.