블로그

튜토리얼

HiAPI API로 flux-1-fill-pro 호출하기: curl, Python 및 비동기 폴링

Nov 12, 2026
HiAPI 블로그 커버 이미지: 짙은 남색 배경 위에 세 겹으로 중첩된 넓은 화살촉 형태가 수평 방향으로 단계적으로 나아가며, 앞쪽 가장자리는 살구색 주황으로 표현된 플랫 신호 흐름도 스타일.
이 페이지에서

flux-1-fill-pro의 역할과 적용 시나리오

flux-1-fill-pro는 인페인팅 계열 이미지 편집 모델입니다. 소스 이미지와 재생성할 영역을 표시한 마스크를 제공하면, 해당 영역이 교체된 새 이미지를 출력합니다. 마스크 밖의 영역은 그대로 유지되어야 하며, 이것이 순수 텍스트-투-이미지 모델이나 전체 이미지 스타일화 모델과의 차이점입니다.

편집이 국소적이고 주변 맥락이 중요할 때 사용해야 합니다:

  • 객체 제거 —— 원하지 않는 요소를 마스크로 표시하고, 그 뒤에 있어야 할 콘텐츠를 모델이 재구성하도록 합니다.
  • 객체 교체 —— 영역을 마스크로 지정하고 프롬프트에 새 콘텐츠를 설명하면서, 장면의 나머지 부분은 그대로 유지합니다.
  • 국소 보정 —— 전체 화면을 재생성하지 않고 텍스처, 반사 또는 작은 결함을 수정합니다.
  • 파이프라인 삽입 —— 제품 이미지, 썸네일 또는 생성된 소재 중 한 영역만 2차 처리가 필요한 경우를 프로그래밍 방식으로 처리합니다.

프롬프트에 따라 완전히 새로운 구도를 원하거나, 마스크 영역이 너무 커서 모델이 사실상 처음부터 이미지를 생성하는 경우에는 적합한 도구가 아닙니다. 그런 경우에는 표준 생성 엔드포인트가 더 예측 가능하게 동작합니다.

이 가이드의 나머지 부분에서는 HiAPI API를 통해 flux-1-fill-pro를 코드에 통합하는 방법을 다룹니다: 요청 구조, curl 호출, Python 동등 구현, 그리고 대부분의 첫 통합에서 실수하기 쉬운 비동기 작업 처리입니다.

준비 작업 및 인증 설정

첫 요청을 보내기 전에 세 가지를 확인하세요.

API 키

HiAPI 계정에서 키를 생성하고 소스 코드 관리에서 분리하세요. 아래 예제는 환경 변수에서 읽으므로 코드 조각을 안전하게 복사할 수 있습니다:

export HIAPI_API_KEY="your_key_here"

Python에서는 os.environ을 통해 동일하게 로드합니다. CI에서 실행하는 경우 .env 파일을 커밋하지 말고 시크릿으로 주입하세요.

모델 식별자

모든 요청은 이름으로 모델을 지정합니다. 이 가이드에서 해당 식별자는 flux-1-fill-pro입니다. 문자열 리터럴을 곳곳에 흩어 놓지 말고 상수로 유지하세요. 나중에 모델을 교체할 때 한 줄만 바꾸면 됩니다.

기본 URL

모든 호출은 플랫폼 참고 문서에 기록된 HiAPI API 기본 URL로 전송됩니다. 키와 함께 설정에 두면 스테이징과 프로덕션 환경을 코드 수정 없이 다르게 구성할 수 있습니다.

시작하기 전에 구조적인 주의점이 있습니다: 인페인팅 요청은 이미지 데이터를 포함합니다. 폼 업로드를 억지로 사용하지 말고 이미지를 base64로 인코딩하여 JSON으로 전송하세요. 또한 클라이언트의 요청 타임아웃을 넉넉하게 유지하세요. 큰 이미지 인코딩은 요청이 프로세스를 떠나기 전부터 지연을 추가합니다. 현재 페이로드 크기 제한은 플랫폼 문서를 확인하고, 소스 이미지가 문서상 한도를 초과하면 엣지에서 요청이 실패하게 두지 말고 인코딩 전에 축소하세요.

인페인팅 요청의 구조

어떤 언어로 작성하든 모든 flux-1-fill-pro 호출은 동일한 논리적 구성을 가집니다.

소스 이미지

편집할 이미지를 문자열로 인코딩한 것입니다. 이는 캔버스를 정의합니다: 크기가 마스크가 위치할 좌표 공간을 결정하고, 콘텐츠가 모델에 인페인팅이 자연스럽게 보이도록 하는 맥락을 제공합니다.

마스크

마스크는 재생성될 영역을 표시합니다. 이것이 가장 흔한 혼란의 원인이므로, 페이로드가 어떤 규약을 따르는지 명확히 하세요: 마스크로 표시된 영역이 모델이 변경할 수 있는 영역입니다. 채울 영역과 유지할 영역이 시각적으로 명확히 구분된 별도 이미지로 마스크를 구성하세요. 마스크를 반전시키는 것은 전형적인 버그입니다. 원하는 영역을 제외한 모든 것을 모델이 편집한 결과를 얻게 됩니다.

마스크는 소스 이미지와 크기가 정확히 일치해야 합니다. 다른 해상도로 그린 마스크는 거부되거나 조용히 어긋나며, 두 경우 모두 왕복 한 번을 낭비합니다.

프롬프트

마스크 내부에 나타나야 할 내용에 대한 텍스트 설명입니다. 구체적이고 국소적으로 유지하세요: 전체 장면이 아니라 콘텐츠와 주변 환경의 조명이나 텍스처 관계를 설명합니다. "가게 정면의 몰딩을 이어가는 목재 벤치, 왼쪽에서 부드러운 오후 빛"이 "더 멋진 배경"보다 모델에 더 많은 근거를 제공합니다.

선택적 제어 항목

문서화된 매개변수 집합에 따라 재현성을 위한 seed나 인페인팅이 원본 픽셀에서 벗어날 수 있는 정도를 제어하는 강도 계열 매개변수를 전달할 수 있을 수도 있습니다. 현재 참고 문서에 없는 매개변수는 이름을 추측하지 말고 지원되지 않는 것으로 처리하세요.

이 네 가지—모델, 프롬프트, 소스 이미지, 마스크—는 모두 동일한 JSON 본문으로 전달됩니다. 다음 두 섹션에서 이 본문을 전송합니다.

실행 가능한 curl 요청

어떤 클라이언트 라이브러리가 가리기 전에 원시 봉투를 볼 수 있도록 curl부터 시작하세요.

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

여기서 request.json은 다음과 같습니다:

{
  "model": "flux-1-fill-pro",
  "prompt": "가게 정면의 몰딩을 이어가는 목재 벤치, 왼쪽에서 부드러운 오후 빛",
  "image": "<base64-encoded source image>",
  "mask": "<base64-encoded mask image>"
}

이 파일을 구성하는 데 유용한 두 가지 요령이 있습니다. 첫째, 수동으로 붙여넣지 말고 명령으로 base64 페이로드를 생성하세요:

base64 -w 0 source.png > source.b64
base64 -w 0 mask.png > mask.b64

그런 다음 작은 jq 또는 Python 단계로 이를 삽입하여 request.json을 조립하세요. 수 메가바이트의 base64 데이터를 수동으로 JSON에 편집해 넣는 것이 페이로드 잘림과 혼란스러운 400 오류의 근원입니다.

응답 해석

응답 봉투는 다음에 무엇을 해야 하는지 알려줍니다. 완료된 작업은 편집된 이미지를 반환합니다. 보통 URL 또는 base64 필드 형태로, 현재 참고 문서가 규정한 형식과 일치합니다. 대기열에 들어간 작업은 식별자와 상태를 반환하며, 이후 폴링합니다(아래 참조). 첫 응답이 항상 픽셀을 포함한다고 가정하지 마세요. 첫날부터 파서가 두 형태를 모두 처리하도록 작성하지 않으면, 부하 상태에서 작업이 대기열에 들어가는 첫 순간에 다시 작성해야 합니다.

응답 본문을 파싱하기 전에 HTTP 상태 코드를 확인하세요. 4xx는 요청 자체에 문제가 있음을 의미하며 재시도는 도움이 되지 않습니다. 대신 페이로드를 수정하세요.

동일한 호출을 Python으로 구현

Python 버전은 동일한 요청이지만 더 편리하게 사용할 수 있습니다. SDK는 필요 없습니다. requests로 HiAPI 엔드포인트를 호출하면 충분합니다.

import base64
import json
import os
import time

import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "flux-1-fill-pro"


def b64(path: str) -> str:
    with open(path, "rb") as f:
        return base64.b64encode(f.read()).decode("ascii")


def create_fill(source_path: str, mask_path: str, prompt: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": b64(source_path),
        "mask": b64(mask_path),
    }
    resp = requests.post(
        f"{BASE_URL}/v1/images/edits",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        data=json.dumps(payload),
        timeout=120,
    )
    if resp.status_code >= 400:
        raise RuntimeError(f"HiAPI error {resp.status_code}: {resp.text}")
    return resp.json()

timeout은 의도적으로 설정했습니다. 큰 이미지 인코딩과 업로드는 일반적인 JSON 호출보다 오래 걸리며, 무제한 요청은 배치 작업에서 스크립트가 조용히 멈추는 원인입니다. 4xx에서 응답 본문을 포함한 예외를 발생시키면 불가사의한 실패가 읽을 수 있는 실패가 됩니다.

모델 식별자와 엔드포인트를 모듈 수준 설정에 두면 버전 업그레이드 시 한 곳만 수정하면 됩니다. 대량의 이미지를 처리하는 경우 호출마다 연결을 다시 설정하지 말고 requests.Session을 재사용하여 연결이 풀링되도록 하세요.

파싱된 사전은 완료된 결과이거나 작업 핸들입니다. 다음 섹션에서 후자를 다룹니다.

비동기 작업 및 폴링 처리

인페인팅 요청은 느릴 수 있으므로 API가 완성된 이미지 대신 작업 핸들을 반환할 수 있습니다. 올바른 패턴은 고정 sleep 후 기도하는 것이 아니라 경계가 있는 폴링 루프입니다.

루프

def wait_for_result(job: dict, *, interval=2.0, timeout=180.0) -> dict:
    deadline = time.monotonic() + timeout
    current = job
    while time.monotonic() < deadline:
        status = current.get("status")
        if status in {"succeeded", "completed"}:
            return current
        if status in {"failed", "canceled", "cancelled"}:
            raise RuntimeError(f"Job ended as {status}: {current}")
        time.sleep(interval)
        interval = min(interval * 1.5, 15.0)  # 완만한 백오프
        current = fetch_job(current["id"])
    raise TimeoutError(f"Job {job.get('id')} exceeded {timeout}s")

fetch_job은 위의 요청 패턴과 동일하게, 작업 id와 인증 헤더를 사용하여 문서화된 작업 상태 엔드포인트에 접근합니다.

고정 간격 대신 백오프를 쓰는 이유

대기열에 대해 빡빡한 루프로 폴링하면 아무 이득 없이 API를 낭비적으로 때립니다. 짧은 간격에서 시작해 상한까지 배수로 늘리면, 빠른 완료 시에는 신속하게 응답하면서 느린 작업에서는 수천 번의 낭비 폴링을 피할 수 있습니다. 간격에 상한을 두면 몇 초 내에 완료를 감지할 수 있습니다.

타임아웃과 실패가 다른 이유

타임아웃은 당신이 기다림을 중단했다는 의미이지 작업이 실패했다는 의미가 아닙니다. 예외를 발생시킬 때 작업 id를 보존하면 호출자가 동일한 작업에 대해 두 번 비용을 지불하고 재제출할 필요 없이 나중에 폴링을 재개할 수 있습니다. 파이프라인에서 타임아웃, 작업 실패, HTTP 오류를 세 가지 다른 예외로 취급하세요. 이를 하나의 일반 오류로 압축하면 프로덕션 장애 디버깅이 훨씬 어려워집니다.

일반적인 장애 디버깅

대부분의 오류 응답은 몇 가지 범주에 속합니다. 다음 순서로 확인하세요.

401 / 403 —— 인증

먼저 확인: 요청 헤더가 정확히 Authorization: Bearer <key>인가, 따옴표나 내보내지 않은 셸 변수에서 비롯된 여분의 공백이 없는가? 빈 $HIAPI_API_KEY는 Bearer라는 단어만 있는 Bearer 토큰을 생성하며, 잘못된 키와 동일한 방식으로 실패합니다.

400 —— 페이로드 형식 오류

먼저 확인: base64 문자열을 연결한 후에도 요청 본문이 유효한 JSON인가? request.json을 추출해 python -m json.tool로 실행해 보세요. 이미지 필드에 data:image/png;base64, 접두사가 붙는 것이 흔한 원인입니다. 참고 문서가 명시적으로 요구하지 않는 한 제거하세요.

마스크/이미지 불일치

먼저 확인: 마스크와 소스 이미지의 픽셀 크기가 정확히 일치하는가? 그런 다음 극성을 검증하세요. 흰색 영역이 모델이 재생성하기를 원하는 영역인지 확인하세요. 결과가 요청한 것과 반대로 보인다면 거의 항상 마스크 반전이며 프롬프트 문제가 아닙니다.

프롬프트 범람

마스크되지 않은 영역이 변했거나 인페인팅이 전역적으로 보인다면, 마스크가 너무 크거나 프롬프트가 전체 장면을 지나치게 덮고 있을 수 있습니다. 둘 다 좁히세요: 마스크를 실제 편집 영역으로 조이고, 마스크 내부 콘텐츠만 설명하세요.

작업 타임아웃

먼저 확인: 페이로드 크기. 과도하게 큰 소스 이미지가 작업이 완료되지 않는 가장 흔한 원인입니다. 먼저 축소하고 한 번 재시도하세요. 여전히 타임아웃되면 작은 테스트 이미지로 참고 한도와 대조한 뒤 서비스 문제로 가정하세요.

결과 필드가 비어 있거나 누락됨

먼저 확인: 대기열 응답의 형태를 처리했는가? 완료된 형태만 읽는 파서는 첫 호출에서 아무것도 보지 못합니다. 개발 중에는 전체 응답 봉투를 로깅하여 방어적 코드를 작성하기 전에 형태를 파악하세요.

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기