HiAPI 输出 URL 过期了？7 天内下载，或将其设为持久存储

TL;DR

• POST /v1/tasks 返回的输出链接是临时的：任务完成后约 7 天就会被删除。每个输出上的 expireAt 以 Unix 秒精确告诉你过期时间。
• 链接一旦过期就无法恢复。再次查询任务只会返回同一个链接，而重新运行任务会再次计费。
• 两种解决办法：任务成功后立即下载文件，或用 "storage": "persistent" 将其保留在 HiAPI 上（每 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 天。我们检查了四个任务（两张图片和两段视频），四个任务的保留窗口都是 7 天。
• status 会依次经过 queued、handling 和 archiving，最终停在 success 或 fail。只有最后这两种才是终态。

链接为什么会“突然”失效

1. 保存的是链接而不是文件。 数据库行、CMS 字段或 Notion 页面里存着 temp.hiapi.ai 的 URL，头一周还能用，之后就所有人都打不开了。
2. 文件获取得太晚。 某个队列几天后才去取结果，已经过了 expireAt。
3. 批处理任务漏掉了上传步骤。 日志看起来没问题，一周后文件却没了。
4. 上一个任务的输出被当作下一个任务的输入。 今天能用，但链接过期后若第二个任务被重新运行就会失败。

办法 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")

在数据库中保存你自己的存储 URL，而不是 HiAPI 的链接。如果提交后进程崩溃，请再次轮询已保存的 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 放在顶层，与 model 同级，而不是放在 input 里面。请检查任务详情中的 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"]'

每次调用最多 50 个 id。响应会列出 accepted 和 rejected 的 id，并为每个被拒绝的 id 给出原因，例如 cap_exceeded。升级在后台运行；文件会保留原有路径并迁移到持久域名。你也可以在 Dashboard → Storage 中执行升级。

	temp（默认）	persistent
保留时长	约 7 天	直到你删除为止
费用	免费	每 GB 每月 $0.05，按天计费
下载	免费	免费
大小上限	无	默认每账户 100 GB

费用示例：存储 5 GB 一个月是 $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 文档 和 任务详情文档。