Os URLs de saída do HiAPI expiraram? Baixe em até 7 dias ou configure como armazenamento persistente

TL;DR

• Os links de saída retornados por POST /v1/tasks são temporários: são excluídos cerca de 7 dias após a conclusão da tarefa. O expireAt de cada saída informa o horário exato de expiração em segundos Unix.
• Depois que um link expira, não há como recuperá-lo. Consultar a tarefa novamente retorna o mesmo link, e executar a tarefa outra vez gera nova cobrança.
• Duas soluções: baixar o arquivo imediatamente após o sucesso da tarefa, ou mantê-lo no HiAPI com "storage": "persistent" (US$ 0,05 por GB por mês). Você também pode fazer upgrade para armazenamento persistente a qualquer momento antes de a saída temporária expirar.

Como é uma tarefa concluída

Abaixo está o detalhe real de uma tarefa obtido de GET https://api.hiapi.ai/v1/tasks/{taskId}:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01M59F0HVM9QSCYPDT4BHABD3K",
    "model": "grok-imagine/text-to-image",
    "status": "success",
    "created": 1792392841,
    "completed": 1792392863,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/.../01M59F0HVM9QSCYPDT4BHABD3K-0.png",
        "expireAt": 1792997663
      }
    ]
  }
}

• storage: "temp" é o nível padrão.
• expireAt menos completed é igual a 604.800 segundos, exatamente 7 dias. Verificamos quatro tarefas (duas imagens e dois vídeos), e todas as quatro tinham uma janela de retenção de 7 dias.
• status passa por queued, handling e archiving, terminando em success ou fail. Apenas esses dois últimos são estados finais.

Por que os links "de repente" param de funcionar

1. Você guardou o link em vez do arquivo. Uma linha de banco de dados, um campo de CMS ou uma página do Notion armazena o URL de temp.hiapi.ai, que funciona na primeira semana e depois ninguém mais consegue abrir.
2. O arquivo foi obtido tarde demais. Alguma fila só buscou o resultado dias depois, já passado o expireAt.
3. A tarefa em lote pulou a etapa de upload. Os logs parecem normais, mas uma semana depois o arquivo sumiu.
4. A saída de uma tarefa foi usada como entrada de outra. Funciona hoje, mas falhará se a segunda tarefa for reexecutada depois que o link expirar.

Solução 1: baixar no mesmo caminho de código

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run_and_save(model, inp, path, timeout_s=600):
    r = requests.post(API, json={"model": model, "input": inp}, headers=H, timeout=30).json()
    if r.get("code") != 200:
        raise RuntimeError(r)
    task_id = r["data"]["taskId"]          # store this before polling
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            out = d["output"][0]
            with open(path, "wb") as f:      # or upload to S3 / R2 here
                f.write(requests.get(out["url"], timeout=120).content)
            return task_id, out["expireAt"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(3)
    raise TimeoutError(task_id)

run_and_save("z-image", {"prompt": "a red ceramic teapot on a wooden table", "aspect_ratio": "1:1"},
             "teapot.png")

Salve no banco de dados o seu próprio URL de armazenamento, e não o link do HiAPI. Se o processo travar após o envio, consulte novamente o taskId salvo em vez de criar uma nova tarefa; dentro de 7 dias o arquivo ainda estará lá.

Solução 2: manter as saídas no HiAPI

Se você não quer montar seu próprio armazenamento, pode pedir ao HiAPI que mantenha os arquivos:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "storage": "persistent",
    "input": {"prompt": "a red ceramic teapot on a wooden table", "aspect_ratio": "1:1"}
  }'

storage fica no nível superior, no mesmo nível de model, e não dentro de input. Verifique data.storage no detalhe da tarefa: se o seu saldo for insuficiente ou você tiver ultrapassado o limite de armazenamento, a saída voltará silenciosamente para temp, e a tarefa ainda será concluída com sucesso.

Já tem algumas saídas temporárias que quer manter? Faça upgrade antes que elas expirem. Primeiro obtenha os ids delas com GET /v1/storages, depois:

curl -s -X POST https://api.hiapi.ai/v1/storages/promote \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '["90216", "90215"]'

Cada chamada aceita no máximo 50 ids. A resposta lista os ids accepted e rejected, com o motivo de cada id rejeitado, por exemplo cap_exceeded. O upgrade é executado em segundo plano; os arquivos mantêm o caminho original e são migrados para o domínio persistente. Você também pode fazer o upgrade em Dashboard → Storage.

	temp (padrão)	persistent
Duração de retenção	Cerca de 7 dias	Até você excluir
Custo	Gratuito	US$ 0,05 por GB por mês, cobrado por dia
Download	Gratuito	Gratuito
Limite de tamanho	Sem limite	Padrão de 100 GB por conta

Exemplo de custo: armazenar 5 GB por um mês custa US$ 0,25; 50 GB custa US$ 2,50. Após excluir arquivos com POST /v1/storages/delete, a cobrança para a partir do dia seguinte. Arquivos persistentes não podem voltar a ser armazenamento temporário.

Se o seu saldo não conseguir pagar os custos de armazenamento por 3 dias consecutivos, os arquivos persistentes entram em um período de carência de 7 dias, e você recebe um e-mail. Os arquivos continuam retidos após a recarga; se o período de carência terminar sem recarga, os arquivos serão excluídos.

Qual solução usar

• Você já tem S3, R2 ou CDN: use a solução 1. Baixe uma vez e sirva a partir do seu próprio armazenamento.
• Você quer que os links permaneçam válidos sem montar seu próprio armazenamento: use a solução 2, definindo "storage": "persistent".
• Você só precisa manter alguns resultados: deixe todas as saídas em temp e faça upgrade apenas das que precisar manter.

FAQ

Por quanto tempo o link de saída é mantido?

Cerca de 7 dias após a conclusão da tarefa. O horário exato está no expireAt de cada saída (segundos Unix).

Consultar a tarefa novamente retorna um novo link?

Não. GET /v1/tasks/{taskId} retorna o mesmo link. Depois que o link expira, o arquivo se perde, a menos que você tenha feito upgrade.

Executar a tarefa novamente custa dinheiro?

Sim. Uma nova tarefa gera nova cobrança, então salvar o arquivo na primeira vez é a opção mais econômica.

Os links de saída são públicos?

Sim. Qualquer pessoa que tiver o URL pode baixar o arquivo, mas o caminho é aleatório e impossível de adivinhar. No momento, não há suporte a links assinados ou links privados.

O armazenamento persistente também conta vídeos?

Sim. Cada arquivo de imagem, vídeo e áudio que você mantém conta para o tamanho de armazenamento.

Consulte a referência completa na documentação de Output Storage e na documentação de detalhes da tarefa.