블로그

튜토리얼

HiAPI API로 flux-2/image-to-image 사용하기: curl 및 Python 튜토리얼

Nov 12, 2026
커버 이미지: 짙은 소나무색 바탕 위에 큰 프리즘 몇 개가 사선으로 잘려 평평한 색면을 이루고, 청록색과 안개 녹색의 기하학적 절단면이 간결하고 질서 있게 배치되어 있다.
이 페이지에서

flux-2/image-to-image의 역할과 적용 시나리오

flux-2/image-to-image는 순수한 텍스트-이미지 생성기가 아니라 편집 엔드포인트입니다. 두 가지를 제공해야 합니다. 참조 이미지와 자연어로 작성된 편집 지시입니다. 모델은 참조 이미지를 시각적 컨텍스트(주체, 구도, 스타일, 조명)로 읽고, 지시를 따르면서도 이 참조 이미지에 고정된 새로운 이미지를 생성합니다.

파이프라인을 설계할 때 이 구분은 중요합니다. 텍스트-이미지를 사용할 때는 모든 것을 처음부터 설명하고 모델이 의도 근처에 안착하기를 기대합니다. 이미지-이미지를 사용할 때는 이미 시각적 소재가 있고, 원하는 것은 제어된 변환입니다. 제품 이미지의 스타일을 재설계하거나, 배경을 교체하거나, 장면 분위기를 조정하거나, 기본 구도를 안정적으로 유지하면서 디자인을 반복하는 것입니다.

적합한 시나리오

  • 소재 변형. 이미 승인된 참조 이미지를 기반으로 여러 스타일화 처리를 생성합니다.
  • 가이드 편집. 전체 장면을 다시 생성하지 않고도 대상 변경(「조명을 더 따뜻하게」「배경을 단색 스튜디오 벽으로 교체」)을 적용합니다.
  • 결과 세트의 일관성. 동일한 참조 이미지를 재사용하여 일괄 출력이 같은 시각적 앵커를 공유하도록 합니다.
  • 인간-기계 협업 도구. 사용자가 이미지를 업로드하고 수정 사항을 설명하면, 자체 인터페이스에서 결과를 받아볼 수 있게 합니다.

부적합한 시나리오

  • 픽셀 단위로 정확한 리터칭이나 합성. 이것은 생성 모델이지 래스터 이미지 편집기가 아닙니다.
  • 참조 이미지가 전혀 없는 경우 — 이 경우 텍스트-이미지가 더 나은 출발점입니다.
  • 지시만으로 모든 세부 사항을 담아야 하는 워크플로; 참조 이미지는 실제로 중요한 역할을 하며, 나쁜 참조 이미지는 나쁜 결과만 낳습니다.

이 엔드포인트를 참조 이미지 + 지시 -> 편집된 이미지로 이해하세요. 이 튜토리얼의 모든 내용은 이 형태를 기반으로 합니다. 어떻게 전송하고, 반환된 결과를 어떻게 읽으며, 네트워크가 협조하지 않을 때 어떻게 계속 실행되게 할지입니다.

사전 요구 사항 및 인증 설정

첫 호출 전에 세 가지를 준비하세요.

1. HiAPI 계정

등록하고 콘솔을 엽니다. 이 튜토리얼의 모든 요청은 HiAPI 통합 API를 통해 발송되므로, 서비스 제공자별로 따로 가입하거나 SDK를 설치할 필요가 없습니다.

2. API 키

콘솔에서 API 키를 생성합니다. 비밀번호처럼 취급하세요. 코드 저장소에 커밋하지 말고, 클라이언트 코드에 붙여넣지 말고, 로그에 기록하지 마세요. 표준 관행은 런타임에 환경 변수에서 로드하는 것입니다.

export HIAPI_API_KEY="your-api-key-here"

그런 다음 키가 필요한 곳에서 HIAPI_API_KEY를 참조합니다. 컨테이너나 서버리스 플랫폼에 배포하는 경우, 이미지에 굽지 말고 해당 환경에서 시크릿으로 설정하세요.

3. 접근 가능한 참조 이미지

이 엔드포인트는 참조 이미지가 필요하므로, 제공 방법을 미리 정해야 합니다. 두 가지 일반적인 방법:

  • URL, API가 가져올 수 있는 예를 들어 자체 객체 스토리지의 서명된 링크.
  • Base64 인코딩된 바이트, 요청 본문에 인라인으로 보내 내부 URL 노출을 피할 수 있지만 페이로드 크기가 증가합니다.

작은 테스트 이미지를 먼저 선택하세요. 몇 백 KB면 통합을 검증하기에 충분합니다. 큰 파일 업로드는 매 재시도를 느리게 만들고 디버깅을 어렵게 합니다.

체크포인트

이제 환경 변수에 저장된 키와 로컬에서 접근 가능한 테스트 이미지가 있어야 합니다. 키가 셸 기록에 남지 않도록 최대한 노력하세요(도구가 로드하는 .env 파일이 보통 명령줄 인라인 내보내기보다 깔끔합니다).

지금부터 길러야 할 습관이 하나 더 있습니다. 첫날부터 요청 ID와 소요 시간을 기록하세요. 프로덕션에서 문제가 발생할 때, 추적 가능한 요청과 추적 불가능한 요청 사이의 차이는 큽니다.

요청 구성: 참조 이미지와 편집 지시

모든 이미지-이미지 호출은 두 입력을 중심으로 구성됩니다. 이 두 가지를 제대로 하면 나머지는 배관 작업입니다.

입력 1: 참조 이미지

참조 이미지는 앵커입니다. 어떤 편집 전에 장면이 무엇을 포함하고 어떻게 보이는지 모델에 알려줍니다. 실용적인 조언:

  • 원하는 출력의 가로세로 비율과 일치시키세요. 참조 이미지가 와이드 가로형인데 정사각형 출력이 필요하다면, 호출 구성에 따라 자르기나 왜곡이 발생할 수 있습니다.
  • 깨끗하고 조명이 좋은 이미지에서 시작하세요. 탁한 참조 이미지는 탁한 편집 결과를 낳습니다.
  • 명확한 주체가 하나 있는 것이 가장 좋습니다. 어수선한 콜라주는 모델에 서로 경쟁하는 앵커를 너무 많이 줍니다.

입력 2: 편집 지시

지시는 원하는 변경에 대한 자연어 설명입니다. 대부분의 품질 차이는 여기서 나옵니다. 참조 이미지가 첨부된 프롬프트로 생각하세요.

  • 전체 장면이 아니라 변경 사항을 서술하세요. 「배경을 순수 흰색 스튜디오 벽으로 교체」가 「흰색 배경의 제품」보다 낫습니다. 후자는 모델이 모든 것을 다시 그리도록 유도합니다.
  • 무엇을 유지해야 하는지 명시하세요. 「주체의 자세와 구도를 변경하지 유지」와 같은 표현은 드리프트를 크게 줄입니다.
  • 스타일과 조명을 구체적으로 지정하세요. 「부드러운 흐린 조명, 낮은 채도」가 「더 예쁘게 만들어」보다 모델에 더 많은 유용한 정보를 줍니다.
  • 모순을 피하세요. 참조 이미지가 낮의 야외 장면인데 밤의 실내를 요구한다면, 모델이 당신이 좋아하지 않을 수 있는 판단을 할 것으로 예상해야 합니다.

요청 본문

flux-2/image-to-image로 보내는 요청은 모델 식별자, 참조 이미지, 지시를 포함합니다. 유용한 멘탈 모델:

{
  "model": "flux-2/image-to-image",
  "input": {
    "image": "<URL 또는 base64 참조 이미지>",
    "prompt": "<편집 지시>"
  }
}

참조 이미지가 base64라면 요청 스키마에 따라 data URI로 구성하거나, 원시 인코딩을 MIME 타입과 함께 전달하세요. URL이라면 호출 중에 해당 링크가 공개적으로 접근 가능한지 확인하세요. 요청 도중에 만료되는 서명 링크는 이해하기 어려운 실패를 낳습니다.

먼저 반복하고, 그다음 통합하세요

무엇이든 코드에 연결하기 전에, 같은 참조 이미지에 대해 두세 개의 지시를 작성하고 출력을 비교하세요. 지시가 구체적일 때 모델은 예측 가능하게 행동하고, 모호할 때는 불안정합니다. 이것을 프로덕션에서 배우는 것보다 지금 배우는 것이 훨씬 저렴합니다.

작동하는 curl 요청

키, 참조 이미지, 지시를 검증하는 가장 빠른 방법은 curl 호출 한 번입니다. 아래 예시는 키가 HIAPI_API_KEY에 있고 참조 이미지가 URL로 접근 가능하다고 가정합니다.

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "image": "https://your-bucket.example.com/reference.jpg",
      "prompt": "배경을 순수 흰색 스튜디오 벽으로 교체하세요. 주체의 자세, 구도, 주체에 비치는 조명은 유지하세요."
    }
  }'

몇 가지 주의할 점:

  • 키는 Authorization 헤더를 통해 bearer 토큰으로 전송됩니다. 절대 URL에 넣지 마세요.
  • Content-Type은 JSON입니다. 설정을 잊는 것은 혼란스러운 4xx의 흔한 원인입니다.
  • 모델 id는 요청 본문에 있습니다. 따라서 같은 엔드포인트에서 필드 하나만 바꿔 다른 모델로 라우팅할 수 있습니다.
  • 지시는 키워드 목록이 아니라 완전한 문장입니다. 이는 의도된 것으로, 이전 섹션을 참조하세요.

원시 출력 읽기

먼저 한 번 실행하고 파싱 코드를 작성하기 전에 전체 응답을 확인하세요. 필요하다면 포매터로 처리하세요:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

요청 본문을 파일(request.json)에 저장하는 것이 셸 인용 문자열을 편집하는 것보다 반복하기 쉽고, 나중에 버그를 재현할 수 있는 지속적인 산출물을 제공합니다.

URL 대신 base64가 필요한 경우

image 값을 파일로 구성한 data URI로 바꾸세요:

python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
    "model": "flux-2/image-to-image",
    "input": {
        "image": f"data:image/jpeg;base64,{data}",
        "prompt": "조명을 더 따뜻하게 하고 대비를 약간 낮추세요.",
    },
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY

이제 페이로드가 request.json에 저장되어 있으므로 동일한 curl 호출이 작동합니다. 호출이 성공하면 Python으로 전환하는 데 필요한 모든 것을 갖춘 것입니다.

Python에서의 동일한 호출

Python 버전은 의도적으로 평범하게 유지합니다. 같은 딕셔너리를 구성하고, 같은 헤더로 전송하며, 엔드포인트와 모델을 상수에 두어 curl 버전과 어긋나지 않게 합니다.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"


def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # 설정되지 않으면 즉시 실패
    payload = {
        "model": MODEL,
        "input": {
            "image": reference_url,
            "prompt": instruction,
        },
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = edit_image(
        "https://your-bucket.example.com/reference.jpg",
        "배경을 순수 흰색 스튜디오 벽으로 교체하세요."
        "주체의 자세, 구도, 주체에 비치는 조명은 유지하세요.",
    )
    print(result)

이렇게 구성한 이유

  • .get() 대신 os.environ["HIAPI_API_KEY"] 사용, 키가 없으면 인증되지 않은 요청을 보내는 대신 즉시 오류가 발생합니다.
  • timeout은 명시적입니다. 이미지 생성은 순간적이지 않습니다. 타임아웃 없는 요청은 결국 워커 프로세스를 멈추게 합니다.
  • 파싱 전에 raise_for_status() 호출. 4xx 또는 5xx에서 예외를 받고 싶지, 나중에 어딘가에서 혼란스러운 KeyError를 받고 싶지 않습니다.
  • 엔드포인트와 모델은 모듈 수준 상수이므로 테스트 스위트를 스텁 서버로 가리키기가 쉽습니다.

base64 입력 사용

URL 대신 바이트를 전달하는 경우, 페이로드를 구성하는 같은 위치에서 파일을 인코딩하고 data URI를 구성하세요:

import base64, pathlib

def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
    raw = pathlib.Path(path).read_bytes()
    return f"data:{mime};base64," + base64.b64encode(raw).decode()

그런 다음 edit_image(as_data_uri("reference.jpg"), instruction)을 호출하세요. 인코딩 단계를 요청 함수와 분리하면 네트워크를 건드리지 않고도 검증과 프롬프트 조립을 단위 테스트할 수 있습니다.

응답 파싱

호출은 JSON 객체를 반환했습니다. 이제 응답에 나중에 필드가 추가되더라도 오류가 나지 않는 방식으로 편집된 이미지를 추출하세요.

가정하지 말고 먼저 확인하세요

개발 중에 원시 응답을 내보내고 이미지 참조가 어디에 있는지 확인하세요. 일반적으로 결과 구조에 URL 또는 base64 페이로드로 포함되어 있습니다. 그런 다음 중첩 키에 바로 파고들지 말고 존재 여부를 확인하는 접근자를 작성하세요.

def extract_image_url(response: dict) -> str:
    data = response.get("data") or []
    if not data:
        raise ValueError(f"응답에 이미지 데이터가 없습니다: {response}")
    first = data[0]
    url = first.get("url") or first.get("b64_json")
    if not url:
        raise ValueError(f"인식할 수 없는 이미지 페이로드: {first}")
    return url

이 코드에서 유지할 만한 두 가지 습관: 오류 메시지에 실제 페이로드를 포함하여 크게 실패하고, 어느 형태(URL 또는 base64)든 허용하며 그중 하나를 하드코딩하지 않는 것입니다. 응답 형식은 진화합니다. 관대한 리더만 살아남습니다.

즉시 영속화

반환된 URL은 일시적일 수 있습니다. 이미지가 중요하다면 같은 작업에서 다운로드하여 자체 버킷에 저장하세요:

def persist(url: str, dest: str) -> None:
    if url.startswith("data:"):
        header, b64 = url.split(",", 1)
        import base64, pathlib
        pathlib.Path(dest).write_bytes(base64.b64decode(b64))
        return
    with requests.get(url, stream=True, timeout=60) as r:
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(1 << 16):
                f.write(chunk)

영속화하면 데이터베이스에 기록할 수 있는 안정적인 키를 얻을 수 있으며, 이는 썩을 수 있는 링크를 저장하는 것보다 훨씬 유용합니다.

얻은 것을 검증하세요

저렴한 검사가 비싼 오류를 발견합니다. 파일이 비어 있지 않은지, 매직 넘버가 어떤 이미지 형식과 일치하는지, 선택적으로 크기가 예상과 맞는지 확인하세요. 경계에서 손상되거나 잘린 이미지를 거부하는 것이 사용자에게 제공하는 것보다 훨씬 좋습니다.

출처 정보 기록

모델 id, 지시 텍스트, 참조 이미지 키, 타임스탬프를 출력과 함께 저장하세요. 3주 후에 누군가 왜 어떤 이미지가 이렇게 보이는지 물으면 그 한 줄의 기록이 답이 됩니다. 특정 편집을 다시 실행하는 것도 간단해집니다.

프로덕션 환경의 재시도 및 오류 처리

이미지 생성 호출은 매우 다른 이유로 실패하며, 이를 한데 묶는 것은 전형적인 프로덕션 버그입니다.

일시적 오류와 최종 오류 구분

  • 일시적 — 타임아웃, 연결 재설정, 429 속도 제한, 5xx 응답. 일시 중지 후 같은 요청을 재시도하면 성공할 가능성이 높습니다.
  • 최종 — 400 잘못된 요청, 401 키 오류 또는 누락, 404 알 수 없는 모델, 페이로드 검증 오류. 이를 재시도하면 시간과 비용을 낭비하고 진짜 수정을 지연시킵니다.

첫 번째 유형만 재시도하세요. 두 번째 유형은 즉시 작업을 실패시키고 오류 메시지를 노출하세요. 거의 항상 어떤 필드가 문제인지 정확히 알려줍니다.

백오프와 지터를 사용한 재시도

import random, time, requests

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
    last = None
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status not in RETRYABLE:
                raise
            last = e
        except (requests.Timeout, requests.ConnectionError) as e:
            last = e
        delay = base * (2 ** i) + random.uniform(0, 0.5)
        time.sleep(delay)
    raise RuntimeError("재시도 횟수가 소진되었습니다") from last

지수 백오프는 이미 힘든 서비스를 강타하는 것을 방지하고, 지터는 워커 배치가 동시에 재시도하는 것을 방지합니다. 항상 시도 횟수와 총 소요 시간을 제한하세요. 무한 루프는 깔끔한 실패보다 나쁩니다.

속도 제한 준수

429를 만나면 백오프 전에 응답 헤더의 재시도 힌트를 따르세요. 대량 작업을 실행하는 경우 서버가 제한하기를 기대하지 말고 자체 측에 동시성 제한을 추가하세요.

실패를 가시화하세요

  • 고유 작업 id로 재시도를 표시하고, 각 시도와 그 결과 및 소요 시간을 기록하세요.
  • 재시도율에 대한 지표를 내보내세요. 서서히 상승하는 것은 업스트림 어딘가가 악화되고 있다는 조기 경고입니다.
  • 마지막 시도가 실패하면 전체 응답 본문과 함께 작업을 데드 레터 큐로 이동하세요. 「failed」 같은 메시지만 남기지 마세요.

멱등성과 비용 합리성

재시도된 요청은 클라이언트가 응답을 보지 못했더라도 서버에서 이미 성공했을 수 있습니다. 제품이 중복 출력을 허용할 수 없다면 자체 id로 작업을 키하고 재시도 전에 대조하세요. 또한 호출은 사용량별로 청구되므로 재시도 루프가 비용을 조용히 증폭시키지 않도록 주의하세요. 멈춰서 영원히 재시도하는 소비자는 이 분야에서 가장 비싼 버그입니다.

흔한 함정과 다음 단계

flux-2/image-to-image 통합의 대부분의 문제는 작은 오류 목록에서 발생합니다. 출시 전에 코드를 이것들과 대조하세요.

  • 모호한 지시. 「개선해」는 무작위 결과를 낳고, 「간판의 글자를 제거하고 간판 모양을 유지해」는 사용 가능한 결과를 낳습니다. 구체성이 품질의 가장 큰 지렛대입니다.
  • 참조 이미지 불일치. 잘못된 가로세로 비율, 흐릿한 원본, 어수선한 콜라주는 더 나은 프롬프트로 구제되지 않습니다.
  • 만료된 URL. 요청 도중에 끊긴 서명 링크는 서버 오류처럼 보이는 실패를 초래합니다. 충분히 긴 유효 기간을 사용하거나 base64로 전환하세요.
  • 응답 구조 하드코딩. 중첩 키에 바로 파고들면 작은 스키마 변경이 장애가 됩니다. 명확한 오류가 있는 방어적 추출기를 사용하세요.
  • 타임아웃 없음. 누락된 타임아웃은 워커 프로세스를 무기한 점유하고 진짜 문제를 가립니다.
  • 최종 오류 재시도. 400은 스스로 고쳐지지 않습니다. 메시지를 읽으세요.
  • 출력 손실. 반환된 URL이 일시적인데 이미지를 영속화하지 않으면 아무것도 없는 것입니다.
  • 기밀 및 프롬프트의 부주의한 기록. 키는 절대 로그에 나타나서는 안 되며, 사용자 제공 지시는 도메인에 따라 마스킹이 필요할 수 있습니다.

다음 단계

단일 호출 흐름이 안정되면 자연스러운 확장은 다음과 같습니다. 호출을 백그라운드 작업으로 감싸 UI가 응답성을 유지하도록 하고, 지시/응답 쌍을 저장하여 프롬프트 문구를 A/B 테스트하며, 사용자가 자체 이미지를 제공하는 경우 입력에 검토 또는 검증 계층을 추가합니다. flux-2/image-to-image 모델 페이지와 HiAPI 문서를 탐색하여 사용 사례에 다음으로 필요할 수 있는 매개변수를 확인하세요. 작동하는 최소한의 것을 구축하고, 측정하고, 지시 품질이 중책을 지도록 하세요.

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

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

API 문서 보기