튜토리얼

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

Jul 30, 2026

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

hiapi의 통합 /v1/tasks 엔드포인트로 flux-2-klein-4b/text-to-image를 호출하는 가장 간단한 curl 및 Python 예제.
'전체 파라미터 표: prompt, aspect_ratio 열거형 값, seed — 엄격한 schema는 알 수 없는 필드를 거부합니다.'
'프로덕션 환경 유의사항: callback.url과 폴링의 트레이드오프, Idempotency-Key 요청 헤더, 그리고 두 가지 오류 응답 패키지 구조.' takeaways:
POST /v1/tasks로 작업을 생성한 다음 GET /v1/tasks/{taskId}를 폴링하거나 callback.url로 결과를 수신하세요.
aspect_ratio는 11가지 명명된 비율을 지원합니다. 이 모델에는 size 또는 n 필드가 없습니다.
재시도 시 동일한 Idempotency-Key 요청 헤더를 사용하면 동일한 taskId가 반환됩니다 — 타임아웃 시 안전하게 재사용할 수 있습니다.
400 오류는 error_code를, 401 인증 오류는 중첩된 error.code를 사용합니다 — 먼저 HTTP 상태 코드를 확인하세요. meta_title: flux-2-klein-4b 텍스트-이미지 API 가이드 meta_description: 'curl과 Python으로 flux-2-klein-4b/text-to-image 호출하기: 작업 생성, 폴링으로 이미지 가져오기, 프로덕션 환경에서 콜백, 멱등성, 오류 처리하기.' keywords:
flux-2-klein-4b 텍스트-이미지 api
flux-2-klein-4b api 예제
hiapi 이미지 생성 api
flux 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-4b/text-to-image를 사용하는 방법

무엇을 만들게 되나요

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

사전 조건: hiapi 콘솔에서 API key를 발급받으세요. 아래의 모든 요청은 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-4b/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.jpg", "expireAt": 1785939579}
    ]
  },
  "message": "success"
}

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

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-4b/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.jpg", "wb").write(image_bytes)

중요 파라미터

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

필드	필수	설명
`prompt`	예	이미지를 설명하는 문자열.
`aspect_ratio`	아니오	다음 중 하나: `1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `21:9`, `9:21`. 생략 시 기본값은 `1:1`입니다.
`seed`	아니오	정수. 동일한 seed를 재사용하면 여러 호출의 결과를 재현할 수 있습니다.

전체 파라미터 참조는 모델 페이지를, 현재 이미지당 가격은 가격 페이지를 참고하세요 — 사용량 기반 가격은 변동되므로 숫자를 하드코딩하지 말고 해당 페이지를 기준으로 삼으세요.

프로덕션 환경 유의사항

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

{
  "model": "flux-2-klein-4b/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바이트). 동일한 계정에서 같은 key로 같은 요청을 재시도해도 두 번째 작업이 생성되지 않습니다 — 원래의 taskId를 돌려받습니다. 이 덕분에 당신 쪽에서 타임아웃된 요청을 중복 과금 없이 안전하게 재시도할 수 있습니다.

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

잘못된 input(prompt 누락, aspect_ratio 범위 초과, 지원되지 않는 필드)은 HTTP 400을 반환하며, 응답 본문은 {"error_code": "INVALID_REQUEST", "message": "..."}입니다.
유효하지 않거나 권한이 없는 API key는 HTTP 401을 반환하며, 응답 패키지 구조가 다릅니다: {"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}.

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

자주 묻는 질문

flux-2-klein-4b/text-to-image는 이미지-투-이미지를 지원하나요? 직접 지원하지 않습니다 — 그것은 자체 입력 schema를 가진 별도의 모델 flux-2-klein-4b/image-to-image입니다.

flux-2-klein-4b와 flux-2-klein-9b의 차이는 무엇인가요? 둘 다 동일한 FLUX.2 [klein] 계열의 텍스트-이미지 엔드포인트이며, 9b가 둘 중 더 큰 모델입니다. 전환하기 전에 9b 모델 페이지에서 현재 가격과 파라미터를 확인하세요.

한 번의 호출로 여러 이미지를 요청할 수 있나요? 아니요 — schema는 n 또는 수량 필드를 허용하지 않습니다. 이미지 한 장당 요청을 한 번씩 보내야 합니다.

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

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

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