Gli URL di output di HiAPI sono scaduti? Scarica entro 7 giorni oppure attiva l'archiviazione persistente

TL;DR

• I link di output restituiti da POST /v1/tasks sono temporanei: vengono eliminati circa 7 giorni dopo il completamento dell'attività. Il campo expireAt su ogni output indica il momento esatto di scadenza in secondi Unix.
• Una volta scaduto, il link non è recuperabile. Interrogare di nuovo l'attività restituisce lo stesso link, mentre rieseguire l'attività comporta un nuovo addebito.
• Due soluzioni: scaricare il file subito dopo il successo dell'attività, oppure conservarlo su HiAPI con "storage": "persistent" ($0,05 per GB al mese). Puoi anche passare all'archiviazione persistente in qualsiasi momento prima della scadenza dell'output temporaneo.

Come appare un'attività completata

Ecco un esempio reale di dettaglio attività restituito da 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" è il livello predefinito.
• expireAt meno completed equivale a 604.800 secondi, esattamente 7 giorni. Abbiamo controllato quattro attività (due immagini e due video) e tutte e quattro avevano una finestra di conservazione di 7 giorni.
• status passa in sequenza da queued a handling e archiving, per terminare in success o fail. Solo questi ultimi due sono stati finali.

Perché i link smettono di funzionare "all'improvviso"

1. Si salva il link invece del file. Una riga di database, un campo CMS o una pagina Notion contengono l'URL di temp.hiapi.ai: per la prima settimana funziona, poi nessuno riesce più ad aprirlo.
2. I file vengono recuperati troppo tardi. Una coda recupera i risultati dopo alcuni giorni, quando expireAt è già passato.
3. Le attività batch saltano il passaggio di caricamento. I log sembrano a posto, ma dopo una settimana i file non ci sono più.
4. L'output di un'attività viene usato come input di quella successiva. Oggi funziona, ma se la seconda attività viene rieseguita dopo la scadenza del link fallirà.

Soluzione 1: scaricare nello stesso percorso di codice

# 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")

Salva nel database il tuo URL di archiviazione, non il link di HiAPI. Se il processo va in crash dopo l'invio, interroga di nuovo il taskId salvato invece di creare una nuova attività: entro 7 giorni il file è ancora lì.

Soluzione 2: conservare gli output su HiAPI

Se non vuoi gestire un tuo sistema di archiviazione, puoi chiedere a HiAPI di conservare i file:

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 va al livello superiore, allo stesso livello di model, non dentro input. Controlla data.storage nel dettaglio dell'attività: se il saldo è insufficiente o hai superato il limite di archiviazione, l'output torna silenziosamente a temp e l'attività risulta comunque completata con successo.

Hai già degli output temporanei che vuoi conservare? Esegui l'upgrade prima che scadano. Recupera i loro id con GET /v1/storages, poi:

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

Ogni chiamata accetta al massimo 50 id. La risposta elenca gli id accepted e rejected, con il motivo per ogni id rifiutato, ad esempio cap_exceeded. L'upgrade avviene in background; i file mantengono il percorso originale e vengono migrati al dominio persistente. Puoi eseguire l'upgrade anche da Dashboard → Storage.

	temp (predefinito)	persistent
Durata di conservazione	Circa 7 giorni	Fino alla tua eliminazione
Costo	Gratuito	$0,05 per GB al mese, con fatturazione giornaliera
Download	Gratuito	Gratuito
Limite di dimensione	Nessuno	100 GB per account per impostazione predefinita

Esempio di costo: conservare 5 GB per un mese costa $0,25; 50 GB costano $2,50. Dopo aver eliminato i file con POST /v1/storages/delete, la fatturazione si interrompe dal giorno successivo. I file persistenti non possono tornare all'archiviazione temporanea.

Se il saldo non è sufficiente a coprire i costi di archiviazione per 3 giorni consecutivi, i file persistenti entrano in un periodo di tolleranza di 7 giorni e riceverai un'email. Ricaricando il saldo i file restano conservati; se alla fine del periodo di tolleranza non hai ancora ricaricato, i file verranno eliminati.

Quale soluzione usare

• Hai già S3, R2 o una CDN: usa la soluzione 1. Scarica una volta, poi servi i file dalla tua archiviazione.
• Vuoi che i link restino validi senza gestire un tuo sistema di archiviazione: usa la soluzione 2, impostando "storage": "persistent".
• Devi conservare solo pochi risultati: lascia tutti gli output in temp e fai l'upgrade solo di quelli da conservare.

FAQ

Per quanto tempo restano validi i link di output?

Circa 7 giorni dopo il completamento dell'attività. Il momento esatto è indicato nell'expireAt di ogni output (secondi Unix).

Interrogando di nuovo l'attività si ottiene un nuovo link?

No. GET /v1/tasks/{taskId} restituisce lo stesso link. Dopo la scadenza, il file non c'è più a meno che tu non abbia eseguito l'upgrade.

Rieseguire l'attività comporta un costo?

Sì. Una nuova attività viene addebitata di nuovo, quindi salvare i file fin dalla prima volta è la scelta più conveniente.

I link di output sono pubblici?

Sì. Chiunque abbia l'URL può scaricare il file, ma il percorso è casuale e impossibile da indovinare. Al momento non sono disponibili link firmati o privati.

L'archiviazione persistente vale anche per i video?

Sì. Ogni file immagine, video e audio che conservi contribuisce alla dimensione di archiviazione.

Per la documentazione completa, consulta la documentazione su Output Storage e la documentazione sul dettaglio delle attività.