FLUX.1 Kontext Max API 사용법? 5분 만에 첫 이미지 생성하기

TL;DR

• 무엇인가: Black Forest Labs가 출시한 FLUX.1 Kontext Max로, 텍스트 생성 이미지와 단일 이미지 편집이 하나의 모델 ID를 공유합니다. HiAPI에 출시되었으며, 모델 페이지 열기에서 프롬프트를 입력하면 바로 생성할 수 있습니다. 신규 가입 시 200 크레딧(약 1.4장 분량)을 지급합니다.
• 가격: 장당 $0.0715(143 크레딧)이며 텍스트 생성 이미지와 편집 가격이 동일합니다. $10으로 약 139장을 생성할 수 있고, 실패한 작업은 사전 차감이 환불됩니다.
• API 호출 방법: POST https://api.hiapi.ai/v1/tasks로 호출하고 model에 flux-1-kontext-max를 입력합니다. taskId를 받은 후 폴링하거나 콜백을 기다렸다가 data.output[0].url에서 결과를 다운로드합니다.

FLUX.1 Kontext Max가 출시된 후 자주 받는 질문은 두 가지입니다. 이미지 편집 시 한 부분만 바꿀 수 있는지, 자체 제품에 연동하는 데 얼마나 걸리는지입니다. 먼저 기능을 살펴보고 두 가지 시작 경로를 안내합니다.

FLUX.1 Kontext Max란 무엇이고, 무엇이 새로운가?

• 하나의 모델 ID로 두 가지 작업을 처리합니다. input에 이미지를 전달하지 않으면 텍스트 생성 이미지, input_image를 전달하면 편집이 되므로 코드를 두 세트로 나눌 필요가 없습니다.
• 편집은 '무엇을 바꾸고 무엇을 유지할지'에 따라 실행됩니다. 재질과 스타일, 요소 추가/삭제, 색상과 조명, 화면 내 텍스트를 모두 변경할 수 있으며, 프롬프트에 언급되지 않은 부분은 최대한 원본 그대로 유지합니다.
• 6가지 화면 비율, 편집 시 원본 비율 유지 가능. aspect_ratio는 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 중 선택할 수 있습니다. 편집 시 비워두면 원본 비율로 출력되며, 픽셀은 32의 배수로 미세 조정되어 1280×720은 1328×752가 됩니다.
• jpeg 또는 png 출력, 장당 약 100만 픽셀. prompt는 최대 4,000자까지 지원하며, 중국어 프롬프트는 자동으로 영어로 번역된 후 생성됩니다.

텍스트 생성 이미지, 16:9. 전체 프롬프트는 아래 curl에 있는 내용과 같으며 그대로 복사할 수 있습니다.

이 프롬프트로 생성하기 →

두 가지 시작 경로: 온라인 체험, 아니면 API?

먼저 결과를 보고 싶다면 온라인 체험, 제품에 연동하려면 API를 사용하세요. 두 경로 모두 동일한 모델과 동일한 가격을 사용합니다.

온라인 체험(약 1분)

1. FLUX.1 Kontext Max 모델 페이지를 열거나 위 이미지 아래의 링크를 클릭하면 프롬프트가 자동으로 입력됩니다.
2. 회원가입 또는 로그인하세요. 신규 계정에는 200 크레딧이 지급됩니다.
3. 16:9를 선택하고 생성 버튼을 클릭하세요.
4. 마음에 들면 다운로드하세요. 이미지를 편집하려면 같은 페이지에서 원본 이미지를 업로드하고 편집 프롬프트를 작성하세요.

API 연동(약 5분)

1. HiAPI 콘솔에서 API Key(sk-...)를 생성하세요.
2. POST /v1/tasks로 작업을 생성하고 응답에서 data.taskId를 받습니다.
3. GET /v1/tasks/{taskId}로 조회하거나 callback.url 알림을 기다린 후, data.status가 success가 되면 data.output[0].url에서 이미지를 다운로드하세요.

장당 $0.0715이며 $10으로 약 139장을 생성할 수 있어 프롬프트를 만족스러울 때까지 조정하기에 충분합니다. 전체 파라미터는 중국어 문서에서 확인하세요.

첫 이미지: curl 버전

작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
      "aspect_ratio": "16:9",
      "output_format": "jpeg",
      "prompt_upsampling": false
    }
  }'

반환된 작업 ID는 data.taskId에 있습니다:

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

결과 조회:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

필수 입력은 prompt뿐입니다. output_format은 기본 jpeg, prompt_upsampling은 기본 비활성화, safety_tolerance는 기본 2(0이 가장 엄격)입니다.

첫 이미지: Python 버전

생성, 폴링, 다운로드를 한 번에 작성했으며 자신의 Key로 교체하면 바로 실행됩니다:

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "flux-1-kontext-max",
    "input": {
        "prompt": "A quiet reading corner by a tall window at golden hour: a linen armchair, a stack of art books and a ceramic cup on a walnut side table, warm afternoon light, soft shadows, editorial interior photography.",
        "aspect_ratio": "16:9",
    },
}

task_id = requests.post(API, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    image_url = data["output"][0]["url"]
    with open("flux-1-kontext-max.jpg", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(data.get("error"))

편집 모드: input_image만 추가하면 충분합니다

input에 input_image를 추가하면 동일한 요청이 텍스트 생성 이미지에서 편집으로 바뀝니다. 아래에서는 위의 독서 공간 이미지를 원본으로 사용하여 안락의자만 교체하고 플로어 램프를 추가합니다:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1-kontext-max",
    "input": {
      "prompt": "Change the linen armchair to a deep forest-green velvet armchair, add a slim brass floor lamp beside it, and keep the window, books, cup, table and afternoon light unchanged.",
      "input_image": "https://static.hiapi.ai/admin-assets/flux-1-kontext-max/2026/10/26/1793005013365-132a4d4eb55e0852-f-t2i-golden.jpg"
    }
  }'

input_image는 공개적으로 접근 가능한 이미지 URL을 받습니다. 편집 시 aspect_ratio를 작성하지 않으면 출력은 원본 비율을 유지합니다. 다중 이미지 합성을 원한다면 GPT Image 2 이미지 편집을 선택하세요. 1–16장의 참조 이미지를 지원합니다.

편집 프롬프트 작성법: 먼저 바꿀 것을 말하고, 유지할 것을 나열하세요

1. 변경 사항을 명확한 지시문 한 문장으로 작성하세요. 대상과 새로운 상태를 구체적으로 작성합니다: linen armchair를 deep forest-green velvet armchair로 교체.
2. 유지 항목을 하나씩 명시하세요. 창문, 책, 컵, 테이블, 오후 광선 등 원본에서 중요한 것을 모두 작성하고 keep ... unchanged로 마무리하세요.
3. 관련 변경은 한 문장에 넣어도 됩니다. 의자를 교체하면서 황동 플로어 램프를 추가하면 모델이 함께 처리합니다. 서로 무관한 수정은 별도로 제출하면 결과를 더 쉽게 확인할 수 있습니다.
4. 화면 내 텍스트를 변경할 때는 레이아웃도 함께 유지하세요. 예를 들어 포스터의 KYOTO를 OSAKA로 바꾸면서 레이아웃, 여백, 폰트 스타일은 그대로 유지하도록 명시하세요.
5. 중국어로 직접 작성해도 됩니다. 시스템이 먼저 영어로 번역한 후 생성하며, 프롬프트는 4,000자 이내로 유지하세요.

출시 전 주의할 4가지

1. 서버 측에서는 콜백을 사용하세요. 요청 본문에 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}을 추가하면 작업이 종료 상태에 도달할 때 자동으로 알림을 받아 폴링을 생략할 수 있습니다.
2. 타임아웃 시 POST를 반복하지 마세요. 매번 생성할 때마다 새 작업이 만들어지고 별도로 과금되므로, 먼저 taskId를 저장하고 재시도 전에 자체 시스템에서 중복을 제거하세요.
3. 결과물 링크는 만료됩니다. data.output[0].url은 임시 링크이므로 받은 즉시 다운로드하여 자체 스토리지에 저장하세요.
4. 픽셀은 32의 배수로 정렬됩니다. 편집 시 aspect_ratio를 비워두면 원본 비율이 유지되고 픽셀이 32의 배수로 미세 조정되어 1280×720은 1328×752로 출력됩니다. 비율을 지정하면 해당 비율로 자르거나 여백을 추가합니다.

자주 묻는 질문

텍스트 생성 이미지와 편집 시 모델을 바꿔야 하나요? 아니요. 동일한 flux-1-kontext-max를 사용하며, input_image 전달 여부에 따라 경로가 결정되고 가격도 동일합니다.

한 번에 참조 이미지를 몇 장 전달할 수 있나요? 한 장입니다. 다중 이미지 합성을 원한다면 GPT Image 2 이미지 편집을 선택하세요. 1–16장의 참조 이미지를 지원합니다.

중국어 프롬프트를 사용할 수 있나요? 네. 프롬프트는 최대 4,000자까지 지원하며, 중국어는 자동으로 영어로 번역된 후 생성됩니다.

편집 후 화면 비율이 바뀌나요? aspect_ratio를 작성하지 않으면 원본 비율을 유지하고 픽셀이 32의 배수로 미세 조정됩니다. 작성하면 지정된 비율로 자르거나 여백을 추가합니다.

작업이 실패하면 과금되나요? 성공적으로 출력된 이미지 장수에 따라 과금되며, 요청당 1장이 반환됩니다. 실패한 작업은 사전 차감이 환불됩니다.

위 독서 공간 프롬프트를 FLUX.1 Kontext Max 모델 페이지에 복사하고 16:9를 선택한 후 한 번 생성해 보세요. 먼저 조명과 재질을 어떻게 처리하는지 확인한 후 프로젝트에 연동할지 결정하세요.