HiAPI の出力 URL が期限切れ？7 日以内にダウンロードするか、永続ストレージに設定しましょう

TL;DR

• POST /v1/tasks が返す出力リンクは一時的なもので、タスク完了後約 7 日で削除されます。各出力の expireAt に Unix 秒で正確な有効期限が示されています。
• リンクは一度期限切れになると復元できません。もう一度タスクを照会しても同じリンクが返るだけで、タスクを再実行すると再度課金されます。
• 解決策は 2 つ：タスク成功後すぐにファイルをダウンロードするか、"storage": "persistent" を指定して HiAPI 上に保持します（1 GB あたり月額 $0.05）。一時出力が期限切れになる前ならいつでも永続ストレージにアップグレードできます。

完了したタスクの見え方

以下は 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" がデフォルトの設定です。
• expireAt から completed を引くと 604,800 秒で、ちょうど 7 日です。4 つのタスク（画像 2 件と動画 2 件）を確認したところ、4 つとも保持期間は 7 日でした。
• status は queued、handling、archiving と順に進み、最終的に success または fail で止まります。終状態となるのはこの最後の 2 つのみです。

リンクが「突然」失効する理由

1. ファイルではなくリンクを保存している。 データベースの行、CMS のフィールド、Notion ページに temp.hiapi.ai の URL を保存すると、最初の 1 週間は使えても、その後は誰も開けなくなります。
2. ファイルの取得が遅すぎる。 あるキューが数日後に結果を取りに行くと、すでに expireAt を過ぎています。
3. バッチ処理でアップロード手順が抜けている。 ログは問題なさそうに見えても、1 週間後にはファイルが消えています。
4. 前のタスクの出力を次のタスクの入力にしている。 今日は使えても、リンクが期限切れになった後で 2 番目のタスクが再実行されると失敗します。

方法 1：同じコードパス内でダウンロードする

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

データベースには HiAPI のリンクではなく、自分自身のストレージ URL を保存してください。送信後にプロセスがクラッシュした場合は、新しいタスクを作成するのではなく、保存しておいた taskId で再度ポーリングしてください。7 日以内ならファイルはまだ残っています。

方法 2：出力を HiAPI 上に保持する

自分でストレージを構築したくない場合は、HiAPI にファイルを保持させることができます：

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 は input の中ではなく、model と同じトップレベルに置きます。タスク詳細の data.storage を確認してください：残高不足やストレージ上限超過の場合、出力は黙って temp にフォールバックしますが、タスク自体は成功します。

すでにある一時出力を保持したい場合は、期限切れになる前にアップグレードします。まず GET /v1/storages でそれらの id を取得し、次に：

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

1 回の呼び出しで最大 50 個の id を指定できます。レスポンスには accepted と rejected の id が一覧表示され、拒否された各 id には cap_exceeded などの理由が付きます。アップグレードはバックグラウンドで実行され、ファイルは元のパスを保ったまま永続ドメインに移行されます。Dashboard → Storage からもアップグレードを実行できます。

	temp（デフォルト）	persistent
保持期間	約 7 日	削除するまで
料金	無料	1 GB あたり月額 $0.05、日割り課金
ダウンロード	無料	無料
サイズ上限	なし	デフォルトでアカウントあたり 100 GB

料金例：5 GB を 1 か月保存すると $0.25、50 GB なら $2.50 です。POST /v1/storages/delete でファイルを削除すると、翌日から課金が停止します。永続ファイルを一時ストレージに戻すことはできません。

残高不足でストレージ料金を 3 日間支払えない場合、永続ファイルは 7 日間の猶予期間に入り、同時にメールが届きます。チャージすればファイルは保持され続けますが、猶予期間が終了してもチャージがない場合、ファイルは削除されます。

どちらの方法を使うべきか

• すでに S3、R2、CDN を持っている： 方法 1 を使います。一度ダウンロードし、自分のストレージから配信します。
• リンクをずっと有効にしたいが、自分でストレージを構築したくない： 方法 2 を使い、"storage": "persistent" を設定します。
• 保持したい結果がわずかしかない： すべての出力を temp のままにし、保持したいものだけをアップグレードします。

FAQ

出力リンクはどのくらい保持されますか？

タスク完了後約 7 日です。正確な時刻は各出力の expireAt（Unix 秒）に示されています。

タスクをもう一度照会すると新しいリンクが取得できますか？

いいえ。GET /v1/tasks/{taskId} は同じリンクを返します。リンクが期限切れになると、アップグレードしていない限りファイルは失われます。

タスクを再実行すると料金がかかりますか？

かかります。新しいタスクは再度課金されるため、最初にファイルを保存しておく方がコストを抑えられます。

出力リンクは公開されていますか？

はい。URL を入手した人は誰でもファイルをダウンロードできますが、パスはランダムで推測できません。現時点では署名付きリンクやプライベートリンクは提供されていません。

永続ストレージは動画も計算対象になりますか？

はい。保持するすべての画像、動画、音声ファイルがストレージサイズに計上されます。

完全なリファレンスは Output Storage ドキュメント と タスク詳細ドキュメント を参照してください。