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

FLUX.2 [klein] 4B는 Black Forest Labs가 선보인 콤팩트하고 빠른 이미지 편집 모델입니다. 참조 이미지 한 장과 자연어 명령을 입력하면 최대 4 MP의 편집된 이미지를 반환합니다. hiapi에서는 이 모델 역시 다른 모든 모델과 동일하게 Unified Async API를 통해 동작합니다. POST /v1/tasks로 작업을 생성한 다음, 폴링하거나 콜백을 받아 결과를 가져옵니다. 본 가이드는 정확한 요청 구조, 바로 사용할 수 있는 curl/Python 예제, 그리고 프로덕션 환경에 연결하는 방법을 다룹니다.

필요한 준비물

• hiapi API 키. dashboard에서 발급받을 수 있으며, 키는 sk-... 형태이고 Authorization: Bearer 요청 헤더에 넣습니다.
• 공개적으로 접근 가능한 참조 이미지 URL(jpeg, png 또는 webp — svg는 지원되지 않음). 4 MP를 초과하는 이미지는 자동으로 4 MP로 축소됩니다.
• flux-2-klein-4b/image-to-image의 현재 가격은 해상도 구간(0.25 MP ~ 4 MP)에 따라 책정됩니다. 실시간 가격은 hiapi pricing에서 확인하고, 여기에 하드코딩하지 마세요.

최소 동작 예제

모델 ID는 flux-2-klein-4b/image-to-image이며, 정확히 이 표기(슬래시 포함)를 model 값으로 사용해야 합니다(URL 경로에 넣지 마세요). 모든 hiapi 모델은 동일한 엔드포인트를 공유하며, input 객체의 필드만 모델별로 다릅니다.

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/image-to-image",
    "input": {
      "prompt": "Keep the subject and camera angle. Replace the background with a deep-blue studio gradient and add soft rim lighting.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

이 요청은 즉시 taskId를 반환합니다. 생성은 비동기로 진행됩니다.

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

결과를 폴링합니다.

curl "https://api.hiapi.ai/v1/tasks/task_..." \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

status가 "success"가 되면 편집된 이미지는 data.output[0].url에 있습니다. 이 URL은 임시 URL(expireAt 포함)이므로 파일을 즉시 다운로드하거나 다시 호스팅하세요. 이 핫링크를 그대로 저장하지 마세요.

Python으로 동일한 흐름을 구현하면 다음과 같습니다.

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Keep the subject and camera angle. Replace the background with a deep-blue "
    "studio gradient and add soft rim lighting.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

요청 파라미터

flux-2-klein-4b/image-to-image는 엄격한 입력 스키마를 따릅니다. 여기에 나열되지 않은 추가 필드는 거부되며 400을 반환합니다.

필드	필수 여부	설명
prompt	예	적용할 편집에 대한 자연어 설명입니다.
image_urls	예	정확히 하나의 참조 이미지 URL을 담은 배열입니다. 여러 개를 전달하면 maxItems: got N, want 1을 반환합니다.
resolution	아니요	허용 값 중 하나: 0.25 MP, 0.5 MP, 1 MP(기본값), 2 MP, 4 MP. 0.25/0.5 MP는 저비용 초안용, 2/4 MP는 최종 출력용으로 사용하세요.
aspect_ratio	아니요	허용 값 중 하나: match_input_image(기본값), 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21.
seed	아니요	나머지가 완전히 동일한 요청 간에 재현 가능한 출력을 얻기 위한 정수입니다.
output_format	아니요	jpg(기본값), png 또는 webp.
output_quality	아니요	jpg/webp의 압축 품질을 지정하는 정수(기본값 95).

이 모델에는 size나 n 필드가 없습니다. 이들은 다른 제공업체의 관례이며 이 스키마에서는 인식되지 않습니다. 각 hiapi 모델은 고유한 필드 집합을 가지므로, 다른 모델용으로 만든 요청을 이식하기 전에 모델 참조 페이지를 확인하세요.

프로덕션 환경 고려 사항

폴링보다 콜백을 우선하세요. 최상위 callback 객체를 추가하면 루프에서 폴링하는 대신 hiapi가 서비스에 알림을 보냅니다.

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when은 "final"만 허용합니다. 작업이 종료 상태(success 또는 fail)에 도달하면 진행 스트림이 아니라 알림을 한 번 보냅니다. 콜백을 깨우기 신호로 취급하세요. 콜백을 받으면 여전히 GET /v1/tasks/<taskId>로 권위 있는 상태를 읽어야 하며, 중복 전달에 대비해 핸들러가 taskId에 대해 멱등성을 유지하도록 하세요.

멱등성. create_task가 반환되면 폴링이나 콜백 대기를 시작하기 전에 taskId를 즉시 영속화하세요. 대기 중 프로세스가 충돌하면 재시작 시 작업을 다시 생성하지 말고 GET /v1/tasks/<taskId>로 복구해야 합니다. 작업 생성은 과금 이벤트이며, GET은 무료로 반복할 수 있습니다.

오류 처리. 유효하지 않거나 권한이 없는 키는 HTTP 401과 구조화된 응답 본문을 반환합니다.

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

request_id를 기록하세요. 지원 팀이 이를 통해 정확한 호출을 찾을 수 있습니다. 형식이 잘못된 input(prompt/image_urls 누락, 지원되지 않는 aspect_ratio 값, 또는 인식할 수 없는 추가 필드)은 error_code: "INVALID_REQUEST"와 함께 400을 반환하며, 메시지에 문제가 된 필드를 명시합니다. 그대로 재시도하지 말고 요청 본문을 수정하세요.

관련 자료

• FLUX.2 [klein] 4B 이미지-투-이미지 모델 참조 — 전체 파라미터 문서와 예제 요청 본문.
• FLUX.2 [klein] 4B 텍스트-투-이미지 모델 참조 — 참조 이미지가 필요 없는 대응 텍스트-투-이미지 변형.
• hiapi pricing — 현재 해상도 구간별 이미지당 비용.
• Unified Async API 개요 — 플랫폼의 모든 모델이 공유하는 POST /v1/tasks / GET /v1/tasks/:id 계약.

자주 묻는 질문

image_urls는 어떤 이미지 형식을 허용하나요? jpeg, png 또는 webp입니다. svg는 지원되지 않습니다. 4 MP를 초과하는 이미지는 편집 전에 자동으로 4 MP로 축소됩니다.

여러 장의 참조 이미지를 전달할 수 있나요? 아니요. 이 모델의 image_urls는 정확히 하나의 요소로 제한됩니다. 더 많이 전달하면 400(maxItems: got N, want 1)을 반환합니다.

왜 "additional properties ... not allowed"라는 메시지와 함께 요청이 거부되나요? 이 스키마는 엄격합니다. 위 파라미터 표에 없는 모든 필드(예: 다른 제공업체의 size, n, strength 등의 관례)는 400을 유발합니다. 정확히 허용되는 필드 집합은 모델 참조에서 확인하세요.

원본 이미지의 가로세로 비율을 유지하려면 어떻게 하나요? aspect_ratio를 match_input_image로 설정하세요. 이 필드를 완전히 생략해도 이것이 기본값입니다.

flux-2-klein-4b/image-to-image와 9B 변형의 차이는 무엇인가요? 둘은 동일한 요청 스키마(prompt, image_urls, resolution, aspect_ratio, seed, output_format, output_quality)를 공유합니다. 9B 경로는 약간의 속도와 비용을 희생해 더 강한 사실감, 텍스트 렌더링, 디테일을 얻습니다. 빠르고 저렴하게 반복할 때는 4B를, 편집이 세밀한 디테일에서 견뎌야 할 때는 9B를 사용하세요.

콜백 URL이 필요한가요, 아니면 폴링으로 충분한가요? GET /v1/tasks/:id로 폴링하는 것은 로컬 개발, 저량 작업, 또는 콜백 전달이 누락될 때의 폴백으로 문제없습니다. 프로덕션 트래픽에서는 콜백이 모든 요청에 폴링 루프를 돌리는 오버헤드를 피할 수 있습니다.