튜토리얼

FLUX.1 Fill Pro API는 어떻게 사용하나요? 5분 만에 첫 마스크 인페인팅 실행하기

마스크의 네 가지 필수 조건, 온라인 체험 4단계, API 연동 4단계, 그리고 바로 실행 가능한 curl과 Python을 제공합니다.

Oct 28, 2026

TL;DR

무엇인가: Black Forest Labs의 마스크 기반 국소 인페인팅 모델입니다. 원본 이미지, 동일 크기의 흑백 마스크, 프롬프트를 업로드하면 흰색 영역만 다시 그리고 검은색 영역은 그대로 유지됩니다. HiAPI에 출시되었으며, 모델 페이지 열기에서 바로 시험해 볼 수 있고, 신규 가입 시 200 크레딧을 지급합니다.
비용: 장당 $0.0715(143 크레딧)이며 성공적으로 생성된 이미지에 대해서만 과금됩니다. steps, guidance, seed, 출력 형식 모두 추가 요금이 없고, 실패 시 사전 차감된 금액은 환불됩니다. $10이면 약 139장입니다.
가장 빠른 호출 방법: POST https://api.hiapi.ai/v1/tasks에 model을 flux-1-fill-pro로 쓰고, input에 image, mask, prompt 세 필드를 넣은 뒤 taskId를 받아 폴링하거나 콜백을 기다린 다음 data.output[0].url을 다운로드합니다.

마스크 인페인팅에서 가장 자주 발목 잡히는 것은 파라미터가 아니라 소재입니다. 마스크는 반드시 원본 이미지와 동일 크기여야 하고, 흰색은 수정할 부분만 덮어야 합니다. 아래에서 이 두 가지를 먼저 정리한 뒤 첫 실행을 해보겠습니다.

FLUX.1 Fill Pro란?

"당신이 표시한 그 부분만 바꾸는" 편집 모델입니다. 변경 범위는 텍스트가 아니라 마스크로 결정되므로 옆의 가구, 그림자, 지평선은 함께 변하지 않습니다.

마스크가 벽시계가 걸린 작은 벽면만 덮었고, 출력은 1440 × 810입니다. 왼쪽의 벽걸이, 편물 접시, 들소 두개골, 화초, 소파, 조명은 모두 다시 그려지지 않았습니다.

세 가지 입력. 원본 이미지(JPEG / PNG / GIF / WebP), 동일 크기의 흑백 마스크, 프롬프트(최대 4,000자).
경계 제어 가능. 흰색은 다시 그리고 검은색은 유지하며, 변경은 마스크 가장자리에서 멈춥니다. 제품 리터칭, 배경 교체, 의류 색상 변경처럼 "한 곳만 손대는" 작업에 적합합니다.
출력은 원본을 따름. 화면 비율 파라미터가 없으며 원본 비율을 그대로 따릅니다. 1600 × 900 원본은 1440 × 810으로 반환되며 32의 배수로 미세 조정됩니다.
파라미터는 충분하되 복잡하지 않음. steps는 15–50(기본 50), guidance는 1.5–100(기본 60), 선택적으로 seed와 jpg / png 출력을 지원합니다.

A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.

이 프롬프트로 생성하기 → 링크는 프롬프트만 미리 채워 줍니다. 원본 이미지 자리는 비어 있고 마스크 자리에는 예시 마스크가 기본으로 들어 있습니다. 본인의 원본 이미지와 동일 크기 마스크로 바꾼 뒤 실행을 누르세요.

마스크는 어떻게 준비하나요?

네 가지 핵심 사항을 이 순서대로 진행하세요.

흑백 두 값만. 흰색은 다시 그릴 영역, 검은색은 유지할 영역입니다. 회색 가장자리는 경계를 흐리게 만들므로 최대한 딱딱한 경계를 만드세요.
크기가 원본과 완전히 일치해야 합니다. 1600 × 900 원본에는 1600 × 900 마스크를 맞춥니다. 화면을 캡처한 뒤 크기를 조정하지 말고, 같은 파일에서 직접 마스크를 내보내세요. 가로세로가 맞지 않으면 작업이 실패합니다.
흰색 영역을 대상에 밀착시키세요. 바꿀 대상만 덮으면 거기서 멈추세요. 옆의 가구, 상판, 그림자를 끌어들이지 마세요.
원본 해상도로 PNG를 내보내세요. PNG는 압축 노이즈가 없어 경계가 가장 깨끗합니다. 마스크와 원본을 공개적으로 접근 가능한 주소에 두세요. API는 파일 업로드가 아니라 URL을 받습니다.

검은색은 유지, 흰색은 다시 그리기. 이 1600 × 900 마스크는 벽시계 위치에만 흰 사각형을 두었으므로 그 벽면만 다시 그려집니다.

온라인 체험: 4단계로 첫 이미지 생성

모델 페이지에서는 마스크를 그릴 수 없습니다. 마스크는 본인 도구에서 미리 만든 뒤 업로드해야 합니다.

FLUX.1 Fill Pro 모델 페이지를 열고 가입 또는 로그인하세요. 새 계정에는 200 크레딧이 제공됩니다.
원본 이미지를 업로드한 뒤, 동일 크기의 흑백 마스크를 업로드하세요.
프롬프트를 붙여넣으세요. 흰색 영역에 나타날 내용만 설명하고, 반드시 유지해야 할 것을 명확히 적으세요.
실행을 누르세요. 기본값은 steps 50, guidance 60, jpg 출력입니다. 먼저 한 번 성공시킨 뒤 파라미터를 조정하세요.

"이 프롬프트로 생성"을 누르면 페이지가 열리며 프롬프트가 자동으로 채워집니다. 원본 이미지 자리는 비어 있고 마스크 자리에는 예시 마스크가 기본으로 들어 있으니, 본인 마스크로 바꾼 뒤 실행하세요.

API 연동: 4단계

콘솔에서 API Key(sk-...)를 생성하세요.
POST /v1/tasks로 작업을 생성하고 input에 image, mask, prompt를 넣으세요.
GET /v1/tasks/{taskId}로 조회하거나, 요청에 callback.url을 추가해 알림을 기다리세요.
data.status가 success가 되면 data.output[0].url에서 이미지를 다운로드해 즉시 본인 저장소에 저장하세요.

전체 필드 표, 오류 코드, 파라미터 설명은 중국어 문서를 참고하세요.

첫 마스크 인페인팅: 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-fill-pro",
    "input": {
      "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
      "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
      "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
      "steps": 50,
      "guidance": 60,
      "output_format": "png"
    }
  }'

반환된 작업 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"

위의 두 이미지는 1:1 대조 소재입니다. 1600 × 900 원본과 동일 크기 마스크로 바로 실행하면 이 글의 첫 번째 액자 그림 효과를 얻을 수 있습니다.

첫 마스크 인페인팅: Python 버전

생성, 폴링, 다운로드를 한 번에 작성했습니다. 본인 Key로 바꾸면 바로 실행됩니다:

import requests, time

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

payload = {
    "model": "flux-1-fill-pro",
    "input": {
        "image": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572565867-4e5072a121d7018f-1792418738578-4e5072a121d7018f-source.jpg",
        "mask": "https://static.hiapi.ai/model-onboarding/flux-1-fill-pro/prod-migrate/2026/10/21/1792572569695-82bb18075f29c864-1792418739459-82bb18075f29c864-mask.png",
        "prompt": "A large framed abstract painting in warm terracotta, sand and cream tones, hanging on the wall, with a thin dark wood frame; keep the room, sofa, furniture and lighting unchanged.",
        "steps": 50,
        "guidance": 60,
        "output_format": "png",
    },
}

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

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

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("fill-pro-edit.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

파라미터는 어떻게 조정하나요?

한 번에 하나씩만 바꾸세요. 그래야 차이가 났을 때 어느 항목의 영향인지 알 수 있습니다.

steps(15–50, 기본 50): 값이 높을수록 디테일이 더 세밀해집니다. 기본값만으로도 결과물에 충분하며, 낮추는 것은 속도가 급할 때만 쓰세요.
guidance(1.5–100, 기본 60): 값이 높을수록 프롬프트에 더 밀착합니다. 스타일이 어긋나면 먼저 올리고, 화면이 뻣뻣해지면 다시 내리세요.
seed: 확정 후 하나의 값으로 고정하면 같은 이미지, 같은 마스크, 같은 프롬프트로 유사한 결과를 재현할 수 있어 롤백과 일괄 통일에 편리합니다.
output_format: 기본값은 jpg입니다. 최대한 많은 디테일을 보존하거나 이후에 다시 처리해야 한다면 png를 쓰세요.
prompt_upsampling: 기본값은 false입니다. 켜면 프롬프트를 자동으로 다시 씁니다. 문구를 완전히 통제하고 싶다면 꺼 두세요.

출시 전 주의할 4가지

페이지에서는 마스크를 그릴 수 없습니다. 모델 페이지와 API 모두 완성된 마스크 이미지만 받으며 크기도 반드시 원본과 일치해야 합니다. 마스크는 Photoshop, Figma, 분할 도구 등에서 미리 만든 뒤 올리세요. 페이지에서는 업로드만 가능하고 그리기는 안 됩니다.
서버에서는 콜백을 사용하세요. 요청 본문에 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}을 추가하면 작업 종료 시 자동으로 알림을 받아 폴링보다 간편합니다. 폴링은 보조 수단으로 남겨 두세요.
타임아웃 시 POST를 반복하지 마세요. POST /v1/tasks를 호출할 때마다 새 작업이 생성되고 별도로 과금됩니다. 먼저 taskId를 저장하고, 재시도 시 같은 작업을 조회하세요.
출력 주소는 만료됩니다. 결과를 받으면 즉시 다운로드해 파일로 저장하고, URL을 영구 주소로 취급하지 마세요. 또한 출력 비율은 원본을 따르고 화면 비율 파라미터가 없으므로, 고정된 레이아웃이 필요하면 직접 비율에 맞게 잘라내세요.

자주 묻는 질문

마스크를 전달하지 않아도 되나요? 아니요. image, mask, prompt 세 가지 모두 필수이며, 마스크는 반드시 원본과 동일 크기의 흑백 이미지여야 합니다.

프롬프트는 얼마나 길게 써야 하나요? 최대 4,000자이지만 충분하면 됩니다. 한 문장은 흰색 영역에 나타날 내용, 한 문장은 반드시 유지할 내용을 쓰세요. 디테일을 구체적으로 설명할수록 결과가 안정적입니다.

출력 크기가 원본과 같은가요? 비율은 같고 픽셀은 32의 배수로 미세 조정됩니다. 1600 × 900 원본은 1440 × 810으로 반환되므로, 원본에 다시 겹치려면 먼저 크기를 통일하세요.

생성 실패 시 비용이 청구되나요? 아니요. 실패한 작업의 사전 차감 금액은 자동으로 전액 환불됩니다.

지금 바로 첫 이미지 만들기

위의 두 대조 소재(원본 + 마스크)로 바로 연습할 수 있습니다. curl의 요청 본문을 복사해 본인 API Key로 바꾸어 한 번 실행하거나, 모델 페이지 열기에서 이 두 이미지를 업로드하세요. 프롬프트는 이미 채워져 있으므로 실행만 누르면 같은 결과가 나옵니다. 이 한 장은 $0.0715이며, 가입 시 받은 200 크레딧으로 한 장을 충분히 생성할 수 있습니다.