Les URL de sortie HiAPI ont expiré ? Téléchargez dans les 7 jours ou passez en stockage persistant

En bref

• Les liens de sortie renvoyés par POST /v1/tasks sont temporaires : ils sont supprimés environ 7 jours après la fin de la tâche. Le champ expireAt de chaque sortie indique précisément l'heure d'expiration en secondes Unix.
• Un lien expiré est irrécupérable. Interroger à nouveau la tâche renvoie le même lien, et relancer la tâche sera facturé de nouveau.
• Deux solutions : télécharger le fichier dès que la tâche réussit, ou le conserver sur HiAPI avec "storage": "persistent" (0,05 $ par Go et par mois). Vous pouvez aussi promouvoir une sortie temporaire en stockage persistant à tout moment avant son expiration.

À quoi ressemble une tâche terminée

Voici le détail réel d'une tâche renvoyé par 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" est le niveau par défaut.
• expireAt moins completed donne 604 800 secondes, soit exactement 7 jours. Nous avons vérifié quatre tâches (deux images et deux vidéos), et les quatre avaient une fenêtre de conservation de 7 jours.
• status passe successivement par queued, handling et archiving, puis se termine par success ou fail. Seuls ces deux derniers états sont finaux.

Pourquoi les liens « cessent soudainement de fonctionner »

1. On conserve le lien au lieu du fichier. Une ligne en base de données, un champ de CMS ou une page Notion contient une URL temp.hiapi.ai ; elle fonctionne la première semaine, puis plus personne ne peut ouvrir le fichier.
2. Le fichier est récupéré trop tard. Une file d'attente ne va chercher le résultat que quelques jours plus tard, après expireAt.
3. Un traitement par lots a omis l'étape d'upload. Les logs semblent normaux, mais une semaine plus tard le fichier a disparu.
4. La sortie d'une tâche sert d'entrée à la suivante. Cela fonctionne aujourd'hui, mais si le lien expire et que la seconde tâche est relancée, elle échouera.

Solution 1 : télécharger dans le même chemin de code

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

Enregistrez votre propre URL de stockage en base de données, et non le lien HiAPI. Si le processus plante après la soumission, interrogez à nouveau le taskId déjà enregistré au lieu de créer une nouvelle tâche ; le fichier reste disponible pendant 7 jours.

Solution 2 : conserver les sorties sur HiAPI

Si vous ne voulez pas monter votre propre stockage, demandez à HiAPI de conserver les fichiers :

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 se place au niveau supérieur, au même niveau que model, et non à l'intérieur de input. Vérifiez data.storage dans le détail de la tâche : si votre solde est insuffisant ou si vous dépassez le quota de stockage, la sortie revient silencieusement à temp, et la tâche réussit quand même.

Vous avez déjà des sorties temporaires à conserver ? Promouvez-les avant leur expiration. Récupérez d'abord leurs identifiants via GET /v1/storages, puis :

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

Chaque appel accepte au maximum 50 identifiants. La réponse liste les identifiants accepted et rejected, avec une raison pour chaque identifiant rejeté, par exemple cap_exceeded. La promotion s'exécute en arrière-plan ; le fichier conserve son chemin d'origine et migre vers le domaine persistant. Vous pouvez aussi effectuer la promotion dans Dashboard → Storage.

	temp (par défaut)	persistent
Durée de conservation	environ 7 jours	jusqu'à ce que vous le supprimiez
Coût	gratuit	0,05 $ par Go et par mois, facturé au jour le jour
Téléchargement	gratuit	gratuit
Taille maximale	illimitée	100 Go par compte par défaut

Exemple de coût : stocker 5 Go pendant un mois coûte 0,25 $ ; 50 Go coûtent 2,50 $. Après suppression des fichiers avec POST /v1/storages/delete, la facturation s'arrête dès le lendemain. Les fichiers persistants ne peuvent plus revenir en stockage temporaire.

Si votre solde ne permet pas de payer les frais de stockage pendant 3 jours consécutifs, les fichiers persistants entrent dans une période de grâce de 7 jours et vous recevez un e-mail. Si vous rechargez, les fichiers sont conservés ; si la période de grâce se termine sans recharge, les fichiers sont supprimés.

Quelle solution choisir

• Vous avez déjà S3, R2 ou un CDN : utilisez la solution 1. Téléchargez une fois, puis servez depuis votre propre stockage.
• Vous voulez des liens qui restent valides sans monter votre propre stockage : utilisez la solution 2 avec "storage": "persistent".
• Vous ne devez conserver qu'un petit nombre de résultats : laissez toutes les sorties en temp et ne promouvez que celles à conserver.

FAQ

Combien de temps les liens de sortie sont-ils conservés ?

Environ 7 jours après la fin de la tâche. L'heure exacte figure dans expireAt (secondes Unix) de chaque sortie.

Interroger à nouveau la tâche donne-t-il un nouveau lien ?

Non. GET /v1/tasks/{taskId} renvoie le même lien. Une fois le lien expiré, le fichier est perdu, sauf si vous l'avez promu.

Relancer une tâche coûte-t-il de l'argent ?

Oui. La nouvelle tâche est facturée de nouveau ; enregistrer le fichier dès la première exécution est donc plus économique.

Les liens de sortie sont-ils publics ?

Oui. Toute personne disposant de l'URL peut télécharger le fichier, mais le chemin est aléatoire et impossible à deviner. Les liens signés ou privés ne sont pas disponibles pour l'instant.

Le stockage persistant compte-t-il aussi les vidéos ?

Oui. Chaque fichier image, vidéo et audio que vous conservez est pris en compte dans la taille de stockage.

Pour la référence complète, voir la documentation Output Storage et la documentation sur le détail des tâches.