튜토리얼

hiapi API로 seedream-5.0-flash 사용하는 방법: curl, Python 및 실행 가능한 요청

Oct 8, 2026

구축할 내용

curl과 Python에서 hiapi의 seedream-5.0-flash 이미지 모델을 호출하는 실행 가능한 통합: 텍스트-투-이미지(또는 이미지 편집) 요청을 제출하고, 결과를 폴링하며, 출력 URL을 다운로드합니다. 끝까지 진행하면 자신의 프로젝트에 바로 넣을 수 있는 스크립트를 얻게 됩니다.

사전 조건

hiapi 계정과 API 키. hiapi 콘솔에서 발급받으세요 — 키는 sk-... 형태입니다.
curl 또는 Python 3.8+ (pip install requests).
이미지 편집 라이브러리는 필요 없습니다 — seedream-5.0-flash는 순수 프롬프트 또는 편집용 입력 이미지 URL이 포함된 프롬프트를 받습니다.

전체 모델 참고: hiapi의 seedream-5.0-flash 및 API 문서 페이지.

최소 실행 예제

hiapi는 하나의 통합 엔드포인트로 모든 생성 모델을 노출합니다: 먼저 작업을 생성한 다음, 완료될 때까지 폴링합니다(또는 콜백을 받습니다).

curl

# 1. 작업 생성
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. 완료될 때까지 폴링
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

input 객체에 대한 설명:

prompt (필수, 1–5000자) — 무엇을 생성할지, 또는 image를 함께 전달하는 경우 무엇을 수정할지.
image (선택, 문자열 또는 최대 10개의 URL/base64 data:image/... URI 배열) — 이 매개변수를 전달하면 처음부터 생성하는 대신 기존 이미지를 편집/참조합니다. 순수 텍스트-투-이미지일 때는 생략하세요.
size (선택, 기본값 "2K") — 사전 설정 값 중 하나인 1K / 1.5K / 2K, 또는 "1536x1024" 같은 사용자 정의 WIDTHxHEIGHT 문자열 (총 픽셀 921,600–4,624,220, 가로세로 비율 1:16에서 16:1 사이).
output_format (선택) — "jpeg" 또는 "png".
background (선택, 기본값 "opaque") — 알파 채널이 있는 이미지를 편집하는 경우에만 "transparent"로 설정하세요.

응답의 output[].url은 서명되고 만료되는 링크(expireAt 필드)입니다 — 이 핫링크를 장기간 보관하지 말고 적시에 다운로드하거나 다시 호스팅하세요.

프로덕션 환경 패턴

폴링 대신 콜백 사용

서버 간 통합의 경우 폴링을 건너뛰고 작업이 완료되면 hiapi가 알려주도록 하세요. model/input 옆에 최상위 callback 객체를 추가하세요(input 내부에 중첩하지 마세요):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final"은 현재 유일하게 지원되는 값입니다 — 작업이 종료 상태(success 또는 fail)에 도달하면 엔드포인트가 정확히 한 번 POST를 받습니다. 전달 재시도를 방지하려면 taskId로 중복을 제거하고, 프로덕션에서 의존하기 전에 엔드포인트가 HTTPS로 접근 가능한지 확인하세요.

폴링 vs. 콜백

프로토타이핑하거나 수명이 짧은 스크립트를 실행하거나 아직 공개 HTTPS 엔드포인트가 없을 때는 폴링을 사용하세요. 간단하지만 지연과 느린 작업의 요청량이 증가합니다.
서비스를 운영할 때는 콜백을 사용하세요 — 낭비되는 폴링 요청이 없고 작업이 완료되는 즉시 알 수 있습니다. 공개적으로 접근 가능한 HTTPS URL이 필요합니다.

멱등성

이미지 생성 자체는 멱등적이지 않습니다(같은 프롬프트라도 두 번 같은 이미지를 반환하지 않음). 따라서 워크플로에 "재시도해도 중복 과금 없음" 의미가 필요하다면, taskId를 자체적으로 추적하고 타임아웃 후 같은 요청을 다시 제출하기 전에 작업 상태를 확인하세요. 무작정 재시도하지 마세요.

오류 처리

permission_denied가 포함된 401 — API 키가 없거나, 형식이 잘못되었거나, 취소되었습니다:
```
{"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}
```
Authorization: Bearer sk-...를 보내고 있는지(원시 키만이 아님), 키가 교체되지 않았는지 다시 확인하세요.
INVALID_REQUEST가 포함된 400 — 일부 필드가 검증을 통과하지 못했습니다. message는 어떤 필드인지, 왜 그런지(예: 범위를 벗어난 size)를 정확히 알려줍니다. 해당 필드를 수정하고 다시 제출하세요. 그대로 재시도하지 마세요.
작업 수준 실패 — HTTP 호출은 성공(200)했지만 작업이 처리 완료 후 status: "fail"로 끝날 수 있습니다. 생성 호출의 HTTP 상태 코드만 보지 말고 항상 폴링/콜백 응답의 data.status를 확인하세요.

자주 묻는 질문

seedream-5.0-flash는 무료인가요? 무료가 아닙니다 — hiapi API 키를 통해 이미지당 과금됩니다. 현재 요금은 가격 페이지를 참고하세요. 유효한 키 없이는 프로덕션 접근이 불가능합니다.

seedream-5.0-flash는 텍스트-투-이미지뿐만 아니라 이미지-투-이미지 편집도 지원하나요? 지원합니다. prompt 옆에 image 필드(URL 또는 base64 data:image/... 문자열, 또는 최대 10개의 배열)를 추가하면 모델이 처음부터 생성하는 대신 참조 이미지를 기반으로 편집/융합합니다.

요청이 200을 반환했는데 이미지가 없는 이유는 무엇인가요? POST /v1/tasks가 200을 반환하는 것은 작업이 수락되었을 뿐입니다 — 생성은 비동기입니다. GET /v1/tasks/<id>를 폴링하거나(또는 콜백을 기다리며) data.status를 확인하세요. 이미지 URL은 status가 "success"일 때만 나타납니다.

1K/1.5K/2K 대신 사용자 정의 해상도를 요청할 수 있나요? 가능합니다 — size를 사전 설정 값 대신 "WIDTHxHEIGHT"(예: "1536x1024")로 전달하세요. 총 픽셀은 921,600에서 4,624,220 사이, 가로세로 비율은 1:16에서 16:1 사이여야 하며, 그렇지 않으면 요청이 400을 반환합니다.

출력 URL은 시간이 지나면 어떻게 되나요? 반환된 output[].url은 expireAt 타임스탬프가 있는 서명 URL입니다 — 영구 저장소가 아닙니다. 작업이 성공하면 가능한 한 빨리 바이트를 다운로드하거나 자체 저장소에 복사하세요.

콜백이 전혀 발생하지 않습니다 — 먼저 무엇을 확인해야 하나요? callback.url이 공개적으로 접근 가능한 HTTPS 엔드포인트인지(localhost나 내부 전용 주소가 아님) 확인하고, callback이 input 내부에 중첩되지 않은 요청 본문의 최상위 필드인지 확인하세요.

핵심 요점

seedream-5.0-flash는 다른 모든 생성 모델과 마찬가지로 hiapi의 통합 POST /v1/tasks 엔드포인트를 통해 호출됩니다.
순수 텍스트-투-이미지일 때는 프롬프트만 전달하거나, 기존 이미지를 편집/참조하려면 `image` 필드(URL 또는 base64, 최대 10개)를 추가하세요.
스크립트와 프로토타입은 GET /v1/tasks/<id>를 폴링하고, 프로덕션 서비스는 `when:"final"`과 함께 최상위 `callback.url`을 사용하세요.
401 permission_denied는 API 키가 유효하지 않거나 취소되었음을 의미하고, 400 INVALID_REQUEST는 일부 필드(보통 `size`)가 검증을 통과하지 못했음을 의미합니다.
출력 URL은 서명되어 있으며 만료됩니다 — 핫링크를 저장하지 말고 적시에 다운로드하거나 다시 호스팅하세요.