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

데이터베이스에는 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"]'

호출당 최대 50개의 id를 전달할 수 있습니다. 응답에는 accepted와 rejected된 id가 나열되며, 거부된 각 id에는 cap_exceeded와 같은 사유가 제공됩니다. 업그레이드는 백그라운드에서 실행되며, 파일은 기존 경로를 유지한 채 영구 도메인으로 마이그레이션됩니다. Dashboard → Storage에서도 업그레이드를 실행할 수 있습니다.

	temp (기본)	persistent
보존 기간	약 7일	삭제할 때까지
비용	무료	GB당 월 $0.05, 일 단위 과금
다운로드	무료	무료
크기 한도	없음	기본 계정당 100GB

비용 예시: 5GB를 한 달 저장하면 $0.25이고, 50GB는 $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 문서와 작업 상세 문서를 참조하세요.