Срок действия выходных URL HiAPI истёк? Скачайте их в течение 7 дней или включите постоянное хранение

TL;DR

• Выходные ссылки, возвращаемые POST /v1/tasks, временные: примерно через 7 дней после завершения задачи они удаляются. Поле expireAt на каждом выходном файле в Unix-секундах точно указывает время истечения.
• После истечения ссылку восстановить нельзя. Повторный запрос задачи вернёт ту же ссылку, а повторный запуск задачи снова тарифицируется.
• Два способа решения: скачать файлы сразу после успешного завершения задачи или сохранить их в HiAPI с помощью "storage": "persistent" (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 хранится URL temp.hiapi.ai, первую неделю он ещё работает, а потом его не может открыть никто.
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, а задача всё равно завершится успешно.

Уже есть временные выходные файлы, которые вы хотите сохранить? Переведите их в постоянное хранилище до истечения срока. Сначала получите их id через GET /v1/storages, затем:

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 дней	Пока вы не удалите
Стоимость	Бесплатно	0,05 $ за ГБ в месяц, тарификация посуточно
Скачивание	Бесплатно	Бесплатно
Максимальный размер	Без ограничений	По умолчанию 100 ГБ на аккаунт

Пример стоимости: хранение 5 ГБ в течение месяца — 0,25 $; 50 ГБ — 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 и документации по деталям задач.