튜토리얼

hiapi API를 통해 flux-2-klein-9b/text-to-image를 사용하는 방법

Jul 30, 2026

slug: flux-2-klein-9b-text-to-image-api-guide locale: en title: hiapi API를 통해 flux-2-klein-9b/text-to-image를 사용하는 방법 category: tutorial summary:

hiapi의 통합 /v1/tasks 엔드포인트를 통해 flux-2-klein-9b/text-to-image를 호출하는 최소 curl 및 Python 예제입니다.
'전체 매개변수 표: prompt, aspect_ratio, num_inference_steps, output_format, seed — 엄격한 스키마는 알 수 없는 필드를 거부합니다.'
'프로덕션 주의사항: callback.url과 폴링의 비교, Idempotency-Key 요청 헤더, 그리고 두 가지 오류 응답 구조. takeaways:
POST /v1/tasks로 작업을 생성한 다음 GET /v1/tasks/{taskId}를 폴링하거나 callback.url을 사용해 결과를 받습니다.
num_inference_steps는 4-8(정수)만 허용합니다. 이 모델에는 size 또는 n 필드가 없습니다.
재시도 시 동일한 Idempotency-Key 요청 헤더를 사용하면 동일한 taskId가 반환됩니다 — 타임아웃 시 안전하게 재사용할 수 있습니다.
400 오류는 error_code를, 401 인증 오류는 중첩된 error.code를 사용합니다 — 먼저 HTTP 상태 코드를 확인하세요. meta_title: flux-2-klein-9b 텍스트-이미지 API 가이드 meta_description: curl과 Python으로 flux-2-klein-9b/text-to-image를 호출하세요. 작업 생성, 이미지 폴링, 프로덕션 환경에서의 콜백, 멱등성, 오류 처리까지 다룹니다. keywords:
flux-2-klein-9b 텍스트-이미지 api
flux-2-klein-9b api 예제
hiapi 이미지 생성 api
flux klein api curl python tags:
api-guide
image-generation
flux author_name: hiapi is_published: false cover_image: https://static.hiapi.ai/blog/_default/recipe-cover.jpg

hiapi API를 통해 flux-2-klein-9b/text-to-image를 사용하는 방법

무엇을 만들게 되나요

프롬프트를 flux-2-klein-9b/text-to-image로 보내고, 이미지 생성이 완료될 때까지 기다린 뒤 다운로드하는 스크립트—그리고 무인 운영 전에 필요한 프로덕션 세부 사항(콜백, 멱등성, 오류 구조)까지 다룹니다.

사전 요구사항: hiapi 콘솔에서 API 키를 발급받으세요. 아래 모든 요청은 Authorization: Bearer sk-<your-api-key>로 인증합니다.

최소 실행 예제

hiapi의 생성 모델은 통합 비동기 엔드포인트 뒤에서 동작합니다. POST /v1/tasks가 작업을 생성하고 즉시 taskId를 반환하면, GET /v1/tasks/{taskId}를 폴링하여 종료 상태에 도달할 때까지 기다립니다.

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

반환 결과:

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

동일한 작업을 폴링하여 data.status가 handling에서 success로 바뀔 때까지 기다립니다(중간에 archiving을 잠시 거칩니다):

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

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../01K...-0.png", "expireAt": 1785941465}
    ]
  },
  "message": "success"
}

data.output[0].url이 생성된 이미지입니다. 임시 링크이며—테스트에서 생성 후 약 7일 뒤 만료됩니다—따라서 해당 URL로 직접 링크하지 말고 바이트를 다운로드해 직접 저장하세요.

Python에서의 동일한 흐름(폴링 포함)

import time
import requests

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

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "flux-2-klein-9b/text-to-image",
    "input": {
        "prompt": "a red fox walking through fresh snow, golden hour light",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "failed":
        raise RuntimeError(f"generation failed: {task}")
    time.sleep(3)

image_bytes = requests.get(image_url).content
open("fox.png", "wb").write(image_bytes)

주요 매개변수

flux-2-klein-9b/text-to-image는 엄격한 입력 스키마를 가집니다. 인식하지 못하는 필드(size, n, negative_prompt, 또는 다른 hiapi 이미지 모델이 허용하는 모든 필드)를 보내면 그대로 거부되므로, 모델 페이지를 먼저 확인하지 않고 모델 간에 매개변수를 복사하지 마세요.

필드	필수 여부	설명
`prompt`	예	이미지를 설명하는 문자열입니다.
`aspect_ratio`	아니오	`1:1`, `4:3`, `3:4`, `16:9`, `9:16` 중 하나입니다. 생략 시 기본값은 `4:3`입니다.
`num_inference_steps`	아니오	정수, 4–8입니다. 기본값은 4이며, 값을 높이면 속도를 희생해 디테일이 약간 더 많아집니다.
`output_format`	아니오	`jpeg`, `png`, `webp` 중 하나입니다. 기본값은 `png`입니다.
`seed`	아니오	정수입니다. seed를 재사용하면 여러 호출의 결과를 재현할 수 있습니다.

전체 매개변수 참조는 모델 페이지를, 현재 이미지당 청구 가격은 가격 페이지를 참조하세요. 사용량 기반 요금은 변동되므로 숫자를 하드코딩하지 말고 해당 페이지에서 확인하세요.

프로덕션 환경 설명

폴링 대신 콜백 사용. 빠른 스크립트 외의 모든 경우에는 폴링 루프를 건너뛰고 작업 생성 요청 본문에 callback.url(및 "when": "final")을 추가하세요. hiapi는 작업 완료 후 결과를 엔드포인트로 POST하며, 페이로드 구조는 GET /v1/tasks/{taskId}가 반환하는 것과 완전히 동일합니다. 콜백 필드 및 서명 검증에 대한 자세한 내용은 작업 생성을 참조하세요.

{
  "model": "flux-2-klein-9b/text-to-image",
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"},
  "input": {"prompt": "a red fox walking through fresh snow, golden hour light"}
}

멱등성. POST /v1/tasks 호출에 Idempotency-Key 요청 헤더를 설정하세요(최대 255바이트). 동일 계정에서 동일한 키로 동일한 요청을 재시도하면 두 번째 작업이 생성되지 않고 원래 taskId를 다시 받습니다. 이 덕분에 클라이언트 측에서 타임아웃된 요청을 중복 청구 없이 안전하게 재시도할 수 있습니다.

오류 처리. 실제로는 두 가지 서로 다른 실패 구조가 나타나므로 둘 다 확인해야 합니다:

잘못된 input(prompt 누락, num_inference_steps 범위 초과, 지원되지 않는 필드)은 HTTP 400과 {"error_code": "INVALID_REQUEST", "message": "..."}를 반환합니다.
유효하지 않거나 권한이 없는 API 키는 HTTP 401과 함께 다른 응답 구조를 반환합니다: {"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}.

먼저 HTTP 상태 코드를 기준으로 분기 처리한 다음, 실제로 존재하는 오류 필드를 읽으세요. 모든 실패가 동일한 응답 구조를 사용한다고 가정하지 마세요.

자주 묻는 질문

flux-2-klein-9b/text-to-image는 이미지-투-이미지를 지원하나요? 직접 지원하지 않습니다. 별도의 모델 flux-2-klein-9b/image-to-image가 있으며 자체 입력 스키마를 가집니다.

flux-2-klein-9b와 flux-2-klein-4b의 차이는 무엇인가요? 둘 다 동일한 FLUX.2 [klein] 계열의 텍스트-이미지 엔드포인트입니다. 9b는 둘 중 더 큰 모델로, 더 강한 사실감, 텍스트 렌더링, 디테일을 목표로 합니다. 전환 전에 4b 모델 페이지에서 현재 가격과 매개변수를 확인하세요.

한 번의 호출로 여러 이미지를 요청할 수 있나요? 아니요. 스키마는 n 또는 개수 관련 필드를 허용하지 않습니다. 이미지마다 요청을 하나씩 보내세요.

반환된 이미지 URL의 유효 기간은 얼마나 되나요? output[0].url은 자체 expireAt 타임스탬프가 있는 임시 링크입니다. 단기 유효(테스트에서 약 일주일)로 간주하고, URL을 저장하지 말고 작업 성공 후 즉시 바이트를 다운로드하세요.

왜 401 permission_denied 오류가 발생하나요? 키가 누락되었거나, 유효하지 않거나, 이 모델에 접근할 권한이 없습니다. 플레이스홀더가 아닌 콘솔에서 발급한 키와 함께 Authorization: Bearer sk-...를 보내고 있는지 확인하세요.

이 API를 사용하려면 자체 서버를 실행해야 하나요? 콜백이 필요할 때만 그렇습니다. 스크립트, 예약 작업, 서버리스 함수에서 GET /v1/tasks/{taskId}를 폴링하는 것은 저용량 사용에 충분합니다. 생성 규모가 커지면 callback.url로 전환하세요.