튜토리얼

flux-2-klein-9b API: curl 및 Python 가이드

Aug 25, 2026

모델: flux-2-klein-9b

hiapi에서 flux-2-klein-9b로 이미지를 한 장 생성하려면 POST /v1/tasks 호출 한 번과 폴링만 있으면 됩니다. 플랫폼의 모든 모델이 사용하는 비동기 작업 패턴과 완전히 동일합니다. 이 가이드는 실제 요청과 응답(작업 생성, 폴링, 최종 이미지 URL)을 기록한 것이므로 아래 코드는 예시용 코드가 아니라 그대로 복사해서 실행할 수 있습니다.

준비할 것

hiapi API 키 — 콘솔에서 생성합니다. 모든 요청은 Bearer token 형태로 전송됩니다.
엔드포인트 접미사를 포함한 전체 모델 ID. flux-2-klein-9b는 flux-2-klein-9b/text-to-image로만 접근할 수 있습니다. flux-2-klein-9b만 쓰면 400이 반환됩니다(아래 참고).

최소 동작 요청(curl)

작업 생성:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a weathered lighthouse on a rocky coast at sunset, cinematic lighting",
      "aspect_ratio": "16:9"
    }
  }'

응답:

{"code":200,"data":{"taskId":"tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM"},"message":"success"}

작업이 완료될 때까지 폴링:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM \
  -H "Authorization: Bearer sk-<your-key>"

완료 시 응답:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T23CG2GNPENYQV4WEKZJTM",
    "status": "success",
    "model": "flux-2-klein-9b/text-to-image",
    "created": 1787581018,
    "completed": 1787581030,
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T23CG2GNPENYQV4WEKZJTM-0.png",
        "artifactId": "96193",
        "expireAt": 1788185830
      }
    ]
  },
  "message": "success"
}

output[0].url이 바로 그 PNG입니다. 테스트에서는 작업이 제출부터 success까지 약 12초가 걸렸습니다. expireAt에 주의하세요. 이 URL이 계속 유효하다고 가정하는 기능을 만들기 전에 아래 저장소 설명을 먼저 읽어 보세요.

Python에서 같은 흐름

import time
import requests

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


def create_image(prompt: str, aspect_ratio: str = "1:1") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={
            "model": "flux-2-klein-9b/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio},
        },
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_image(task_id: str, timeout_s: int = 120, interval_s: int = 3) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_image("a weathered lighthouse on a rocky coast at sunset, cinematic lighting", "16:9")
    image_url = wait_for_image(task_id)
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print(f"saved output.png from task {task_id}")

flux-2-klein-9b가 실제로 검증하는 파라미터

입력 스키마는 매우 엄격합니다. 나열되지 않은 필드를 보내면 API는 요청이 큐에 들어가기 전에 전체 요청을 거부합니다:

prompt(문자열, 필수) — 유일한 필수 필드입니다.
aspect_ratio(문자열, 선택) — 값은 1:1, 4:3, 3:4, 16:9, 9:16 중 하나입니다. 다른 값을 보내면 400과 함께 value must be one of ...가 반환됩니다.
seed(정수, 선택) — 같은 prompt에 같은 seed를 전달하면 재현 가능한 결과를 얻을 수 있습니다.
output_format(문자열, 선택) — 값은 jpeg, png, webp 중 하나입니다.

이것이 스키마의 전부입니다. size, quality, strength, n 필드는 없습니다. 이 중 하나라도 보내면 실패합니다:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'size' not allowed"}

flux-2-klein-9b는 텍스트-이미지 생성만 지원합니다. image_urls도 허용하지 않습니다. 이미지-이미지가 필요하면 입력 구조가 다른 별도의 flux-2-klein-9b/image-to-image 모델 ID를 사용하세요.

모델 ID에는 엔드포인트 접미사가 필요합니다

hiapi의 일부 모델은 맨 ID로도 해석됩니다(예: gpt-image-2). 하지만 flux-2-klein-9b는 그런 모델이 아닙니다. 접미사를 빼면 작업이 아예 생성되지 않습니다:

{"code":400,"data":null,"error_code":"MODEL_UNAVAILABLE","message":"model not available via /v1/tasks"}

항상 전체 flux-2-klein-9b/text-to-image 문자열을 model로 보내세요.

프로덕션 환경 유의 사항

두 가지 서로 다른 오류 구조. 검증 오류(필드 누락, 잘못된 열거 값, 알 수 없는 키)는 최상위 {"code":400,"error_code":"INVALID_REQUEST","message":"..."} 형태로 반환됩니다. 인증/권한 오류는 {"error":{"code":"permission_denied","message":"...","request_id":"..."}} 형태로 반환되며, 중첩된 error 객체와 HTTP 401입니다. 오류 처리에서는 두 구조를 모두 확인해야 합니다. resp["code"]만 확인하는 코드는 401 상황을 놓칩니다.
permission_denied는 요청이 아니라 키를 의미합니다. prompt가 존재하고 타입도 올바른데도 401 permission_denied를 받는다면, 해당 API 키 자체에 이 모델이 활성화되지 않은 것입니다. JSON을 반복해서 확인하지 말고 콘솔에서 확인하세요.
출력 저장소는 임시입니다. storage: "temp"이며 각 출력에는 expireAt unix 타임스탬프가 붙습니다. 캡처한 예시에서는 생성 후 약 일주일이었습니다. 작업이 성공하면 즉시 파일을 다운로드하거나 자체 저장소로 푸시해야 합니다. temp.hiapi.ai URL을 영구 주소로 저장하지 마세요.
대량 작업에는 콜백을 사용하세요. 이미지 한 장 폴링은 괜찮지만 50장을 폴링하면 50번의 반복 왕복이 됩니다. 생성 요청의 최상위에 callback: {"url": "...", "when": "final"}을 설정하면 hiapi가 작업이 실제로 완료될 때 결과를 한 번에 푸시해 줍니다. 현재 when은 "final" 하나만 지원합니다.
재시도는 taskId를 받기 전에, 이후가 아니라. 최초 POST /v1/tasks에서 네트워크 오류나 5xx가 발생하면 안전하게 재시도할 수 있습니다. 이 시점에는 아직 아무것도 생성되지 않았습니다. 일단 taskId를 받았다면 같은 prompt를 다시 제출하면 별개의 두 번째 이미지가 생성됩니다. 이때는 폴링하거나 콜백을 기다려야 합니다.

자주 묻는 질문

왜 flux-2-klein-9b를 호출하면 MODEL_UNAVAILABLE이 나오나요? 모델 ID에 엔드포인트 접미사가 필요합니다. 맨 flux-2-klein-9b가 아니라 flux-2-klein-9b/text-to-image를 사용하세요.

flux-2-klein-9b는 어떤 화면 비율을 지원하나요? 다섯 가지입니다: 1:1, 4:3, 3:4, 16:9, 9:16. 다른 값은 400과 함께 이 다섯 값을 나열하는 value must be one of 메시지가 반환됩니다.

출력 품질이나 해상도를 제어할 수 있나요? 아니요. 스키마는 prompt, aspect_ratio, seed, output_format만 허용합니다. size나 quality 파라미터는 없으며, 그중 하나를 보내면 additional properties 400 오류가 반환됩니다.

flux-2-klein-9b로 이미지-이미지 편집을 할 수 있나요? 이 모델 ID로는 안 됩니다. 입력 스키마가 별도로 있는 flux-2-klein-9b/image-to-image를 사용하세요.

출력 URL의 유효 기간은 얼마나 되나요? storage가 "temp"이며 각 출력에는 expireAt unix 타임스탬프가 붙고, 실제로는 약 일주일 후입니다. 작업 성공 후 즉시 파일을 다운로드하거나 다시 업로드하세요. URL을 영구 주소로 취급하지 마세요.

다른 모델에서는 되는 키가 이 모델에서 401이 나오는 이유는 무엇인가요? 모델 접근 권한은 키별로 부여됩니다. 401과 error_code: "permission_denied"가 반환된다는 것은 이 특정 키에 flux-2-klein-9b 권한이 아직 없다는 뜻입니다. 콘솔에서 활성화하세요. 요청 본문의 버그가 아닙니다.