블로그

튜토리얼

HiAPI API로 fibo-edit-1.5 이미지 투 이미지 호출하기: curl 및 Python 가이드

명령 기반 이미지 편집을 위한 실행 가능한 요청 실전 안내

Nov 17, 2026
커버 이미지: 거의 검은 배경 위에 성기게 시작해 빽빽해지는 민트 그린 점 띠가 있고, 오른쪽 가장자리에 짙은 청록 점 무리가 장식되어 있다.
이 페이지에서

fibo-edit-1.5 이미지 투 이미지 엔드포인트가 할 수 있는 일

fibo-edit-1.5/image-to-image는 명령 기반 이미지 편집 엔드포인트입니다. 장면을 처음부터 묘사하는 대신 참조 이미지와 자연어 지시문을 받아, 해당 편집을 적용하면서 나머지 구도는 유지한 새 이미지를 반환합니다.

이러한 특성은 요청을 설계하는 방식에 직접 영향을 줍니다. 참조 이미지는 시각적 맥락(피사체, 구도, 조명, 스타일)을 담고, 지시문은 변경 사항을 담습니다. 좋은 지시문은 무엇을 바꿀지 명확히 밝히고, 그대로 유지할 부분에 대해서는 침묵합니다. “하늘을 흐린 일몰로 교체하고 건물과 전경은 그대로 유지”는 “더 좋게 만들어 줘”보다 훨씬 많은 정보를 전달합니다.

성공적인 호출은 편집된 이미지 리소스를 산출합니다. 엔드포인트 호출 방식에 따라 응답은 저장하거나 가져올 수 있는 형태로 생성된 출력을 반환합니다. 정확한 응답 구조와 지원되는 파라미터는 엔드포인트 참조에서 확인하세요. 필드 이름, 허용되는 이미지 형식, 크기 제한은 이 문서와 별개로 변경될 수 있으므로 해당 참조를 유일한 기준으로 삼아야 합니다.

대표적인 용도로는 제품 사진 보정, 배경 교체, 스타일 조정, 전체 이미지 재생성으로는 충실도를 잃을 수 있는 부분 편집 등이 있습니다. 텍스트에서 이미지를 생성하는 작업이라면 이 엔드포인트는 적합한 도구가 아닙니다. 텍스트 투 이미지 모델을 사용하세요.

초기에 확립해야 할 기대치는 편집이 본질적으로 반복 작업이라는 점입니다. 첫 지시문이 완벽하게 맞는 경우는 드물기 때문에, 저비용 반복을 중심으로 워크플로를 구성하세요. 한 번에 변수 하나만 바꾸고, 참조 이미지는 그대로 유지하며, 다음 단계로 넘어가기 전에 출력을 비교하세요.

동작하는 요청의 구성 요소

코드를 작성하기 전에 요청에 필요한 입력을 정리해 두세요. fibo-edit-1.5/image-to-image 호출은 매번 네 가지 유형의 정보를 조합합니다.

인증

모든 요청은 HiAPI 통합 인터페이스를 통과하며, Authorization 헤더에 API 키를 담습니다. 키는 소스 코드가 아니라 환경 변수에 두고, 절대 커밋하지 마세요.

참조 이미지

편집 대상이 되는 원본 이미지를 제공해야 합니다. 일반적인 형태는 두 가지입니다. 서비스가 가져올 수 있는 공개 URL 또는 JSON 요청 본문에 임베드된 base64 인코딩 데이터입니다. URL은 반복 작업에 더 편리하고, base64는 외부 호스팅 의존성을 피할 수 있습니다. 허용되는 형식과 크기 또는 해상도 제약은 엔드포인트 참조에서 확인하세요.

편집 지시문

변경 사항을 설명하는 일상 언어 문자열입니다. 명령형 문장으로 작성하고, 변경할 영역이나 요소를 지정하며, 유지해야 할 부분을 명시하세요. 관련 없는 여러 편집을 하나의 지시문에 몰아넣지 마세요. 호출을 여러 번으로 나누어야 어떤 편집이 나쁜 결과를 초래했는지 판단할 수 있습니다.

출력 제어

크기, 출력 형식, 후보 이미지 수 같은 선택적 설정입니다. 첫 호출에서는 기본값을 유지하고, 이후에 의도적으로 조정하세요. 설정하는 모든 파라미터는 문제가 생겼을 때 배제해야 할 변수가 하나 더 늘어나는 것입니다.

따라서 최소 요청 본문에는 이미지와 지시문이라는 두 가지 실질적 필드가 JSON 객체로 감싸져 있고, 선택적으로 출력 기본 설정이 붙습니다. “어떤 이미지, 어떤 변경, 어떤 형식으로 반환받을지”에 답할 수 있다면 호출을 작성할 준비가 된 것입니다.

curl로 호출하기

curl부터 시작하세요. HTTP 계층을 분리해 주므로 문제가 생겼을 때 애플리케이션 코드가 아니라 요청 자체에 문제가 있음을 알 수 있습니다.

먼저 키를 내보내세요:

 export HIAPI_API_KEY="your-api-key"

그다음 참조 이미지 URL과 지시문이 담긴 JSON 요청 본문을 전송하세요:

curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/input.jpg",
    "prompt": "평범한 하늘을 부드러운 일몰 그라데이션으로 교체하고, 건물과 전경은 그대로 유지하세요."
  }'

몇 가지 실용적인 조언:

  • 기본 URL과 경로는 기억에 의존하지 말고 엔드포인트 참조에서 확인하세요.
  • -sS를 사용해 curl이 성공 시에는 조용히 있고, 전송 오류는 여전히 표시하도록 하세요.
  • 외부 호스팅에 의존하고 싶지 않다면 파일을 base64로 인코딩하고 image 값을 인코딩된 문자열로 바꾸되, 참조에 지정된 필드 이름과 일치시키세요.
  • 탐색 단계에서는 출력을 jq .로 파이프해 응답을 읽기 쉽게 만드세요.

응답을 확인하려면 반환된 이미지 페이로드나 URL을 찾아 여세요. 응답 본문에 오류 객체가 있다면 type과 message 필드를 기록하세요. 이 필드들이 이미지, 지시문, 요청 구조 중 어디에 문제가 있는지 알려줍니다. 성공한 원시 응답을 파일로 저장하세요. Python 클라이언트를 작성할 때의 테스트 픽스처가 되고, 나중에 동작이 바뀌었을 때의 증거가 됩니다.

Python으로 동일한 요청 보내기

Python 버전은 curl 호출과 완전히 일치해야 합니다. 같은 경로, 같은 헤더, 같은 요청 본문이어야 하므로, 차이가 있다면 요청 내용의 차이가 아니라 코드의 버그입니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"

payload = {
    "image": "https://example.com/input.jpg",
    "prompt": (
        "평범한 하늘을 부드러운 일몰 그라데이션으로 교체하고, "
        "건물과 전경은 그대로 유지하세요."
    ),
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)

로컬 파일 전송

디스크에 있는 파일을 편집하는 경우, URL 대신 파일을 인코딩해 문자열로 전송하세요:

import base64

with open("input.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "image": encoded,
    "prompt": "배경을 깔끔한 중립 회색으로 바꾸고, 제품은 선명하게 유지하세요.",
}

이 방식을 사용하기 전에 엔드포인트 참조에서 정확한 필드 이름과 예상 인코딩을 확인하세요.

출력 저장

반환된 이미지를 디스크에 기록해 반복 결과를 나란히 비교하고, 어떤 지시문이 어떤 결과를 만들었는지 기록하세요. 지시문 해시로 도출한 이름으로 출력을 저장하는 작은 도우미 함수가 있으면 이후 비교가 매우 쉬워집니다.

반드시 명시적인 timeout을 설정하세요. 이미지 편집은 단순 텍스트 호출보다 오래 걸리며, 타임아웃이 없는 요청은 네트워크가 멈출 때 작업 프로세스를 무기한 매달리게 만듭니다.

오류 처리와 안전한 재시도

실패는 몇 가지 큰 범주로 나뉘며, 각 범주에는 다른 대응이 필요합니다.

클라이언트 오류

요청 자체에 문제가 있습니다. JSON 형식 오류, 이미지 필드 누락, 지원되지 않는 이미지 형식, 모델이 수행할 수 없는 지시문, 인증 문제 등입니다. 이런 오류를 그대로 재시도하면 시간과 할당량만 낭비하며 똑같이 실패합니다. 대신 요청을 수정하세요. 이런 오류가 발생하면 전체 요청 본문(이미지 부분은 잘라서)과 오류 메시지를 기록한 뒤 입력을 수정하세요.

속도 제한

허용된 할당량보다 빠르게 요청을 보냈습니다. 올바른 대응은 엔드포인트를 마구 두드리는 것이 아니라 물러났다가 재시도하는 것입니다. 응답에 재시도 안내가 있으면 따르고, 없으면 지수 백오프를 사용하세요.

서버 및 일시적 오류

타임아웃, 연결 재설정, 상위 서비스 장애는 재시도할 가치가 있습니다. 바로 이 지점에서 멱등 재시도 로직이 필요합니다.

실용적인 재시도 전략

  • 타임아웃, 연결 오류, 속도 제한 또는 서버 응답에 대해서만 재시도합니다.
  • 상한이 있는 지수 백오프를 사용하세요. 예를 들어 짧은 지연으로 시작해 시도할 때마다 두 배로 늘리고, 정해진 소수 횟수 후 중단합니다.
  • 병렬 작업 프로세스가 같은 순간에 모두 재시도하지 않도록 지연에 지터를 추가하세요.
  • 스키마, 형식, 지시문 문제로 거부된 요청은 절대 재시도하지 마세요.
  • 각 시도와 시도 횟수 및 결과를 기록해 실패가 집중되는지 확인하세요.
import random, time, requests

def edit_with_retry(payload, attempts=4):
    delay = 1.0
    for i in range(attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
        except (requests.Timeout, requests.ConnectionError):
            pass
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                r.raise_for_status()
        time.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 2, 30)
    raise RuntimeError("재시도 후에도 편집이 실패했습니다")

이 코드는 골격으로 보세요. 재시도 가능한 상태 코드를 엔드포인트가 실제로 반환하는 값과 맞추고, 전략을 한곳에 모아 모든 호출자가 공유하도록 하세요.

출시 전 점검

엔드포인트를 프로덕션에 연결하기 전에 짧은 체크리스트를 완료하세요.

정상 경로를 두 번 검증

저장해 둔 curl 호출과 Python 클라이언트를 동일한 입력으로 다시 실행해 동등한 결과가 나오는지 확인하세요. 결과가 다르다면 요청 본문이 실제로 동일하지 않은 것입니다.

실제 입력으로 지시문 보정

단일 샘플이 아니라 대표성 있는 이미지로 지시문을 테스트하세요. 편집 품질은 지시문의 구체성과 참조 이미지가 해당 변경을 얼마나 잘 뒷받침하는지에 크게 좌우됩니다. 작은 프롬프트-출력 쌍 세트를 회귀 테스트 모음으로 보관하세요. 문구를 조정할 때哪些 개선되었고哪些 퇴보했는지 확인할 수 있습니다.

제한과 형식 확인

엔드포인트 참조에서 허용되는 이미지 형식, 최대 크기, 요청 크기 상한을 확인하세요. 전송 전에 로컬에서 검증하세요. 클라이언트에서 잘못된 이미지를 거부하는 편이 왕복 한 번보다 빠르고 저렴합니다.

키와 로그 검증

API 키가 환경 변수에서 오는지, 요청 로그가 이미지 페이로드를 잘라내는지, 오류 보고서에 어떤 키도 나타나지 않는지 확인하세요.

실패 동작 확인

스테이징 환경에서 타임아웃과 잘못된 형식의 요청 본문을 강제로 발생시켜, 재시도 전략이 올바르게 작동하는지, 영구적 실패가 조용히 사라지지 않고 호출자에게 노출되는지 확인하세요.

이 모든 것이 통과되면 통합은 가장 좋은 의미에서 평범해집니다. 권위 있는 파라미터 목록은 fibo-edit-1.5 이미지 투 이미지 엔드포인트 참조에서 확인한 뒤, 동작하는 curl 호출에서 바깥으로 확장해 나가세요.

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

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

API 문서 보기