블로그

튜토리얼

HiAPI API로 fibo-2.0/image-to-image 호출하기: curl과 Python 실습

Nov 13, 2026
커버 이미지: 어긋나게 겹쳐진 뼈색 종이와 차콜 블랙 가장자리 선, 그 사이에 끼워진 녹슨 붉은색 종이 한 장, 평면 구성.
이 페이지에서

fibo-2.0/image-to-image의 파이프라인 내 위치

텍스트-투-이미지 모델은 프롬프트 한 줄에서 시작하지만, 이미지-투-이미지 모델은 이미 가지고 있는 이미지에서 시작합니다. 이 차이는 작아 보이지만 모델이 파이프라인에서 차지하는 위치를 결정합니다. fibo-2.0/image-to-image는 처음부터 소재를 만드는 첫 단계가 아니라, 기존 이미지를 변형하는 편집 단계입니다.

일반적인 워크플로는 이렇습니다. 기초 이미지를 얻거나 생성한 뒤, 원하는 변경을 설명하는 지시와 함께 fibo-2.0/image-to-image로 보내고, 반환된 결과를 후속 단계—검수, 합성, 저장, 또는 또 다른 모델 호출—로 넘깁니다. 모델이 입력 이미지와 프롬프트를 동시에 받기 때문에, 설명한 부분의 스타일을 다시 그리거나 조정·변형하면서 구도, 피사체 위치, 전반적 구조를 유지할 수 있습니다.

텍스트-투-이미지 대신 이미지-투-이미지를 선택할 때

출력이 기존 이미지와 식별 가능한 연관성을 가져야 할 때 이미지-투-이미지를 선택합니다. 피사체를 유지한 채 사진 스타일을 다시 그리기, 조명이나 색감 조정, 승인된 소재의 변형 생성, 최종 사용 전 거친 밑그림 정리 등이 그렇습니다. 시작 이미지 없이 설명만 있다면 텍스트-투-이미지를 선택합니다.

이 엔드포인트가 요구하는 것

이 호출은 작업 제출입니다. 입력 이미지, 프롬프트, 제어하려는 파라미터를 보내면 API가 추적 가능한 작업을 반환합니다. 이 엔드포인트는 완성된 편집 애플리케이션이 아니라 더 큰 체인 속의 명확히 정의된 한 단계로 봐야 합니다. 입력 이미지를 어떻게 준비하고 결과를 어떻게 처리할지는 사용자의 몫입니다.

요청이 본질적으로 비동기이므로 통합 설계도 그 점을 중심으로 해야 합니다. 제출하고, 작업 식별자를 저장하고, 작업이 완료될 때까지 폴링한 다음, 출력 참조를 가져옵니다. 이 가이드의 나머지 부분이 바로 이 흐름을 구축합니다.

요청을 보내기 전 준비

첫 호출 전에 세 가지를 준비해야 합니다. 자격 증명, 엔드포인트 형태에 대한 정확한 이해, 그리고 준비된 입력 이미지입니다.

자격 증명

HiAPI API로 가는 모든 요청은 API 키로 인증됩니다. 키는 반드시 서버 측에 보관해야 하며, 브라우저 코드에 넣거나 코드 저장소에 커밋해서는 절대 안 됩니다. 가장 깔끔한 방법은 환경 변수에서 읽어, 동일한 코드가 로컬과 배포 환경 모두에서 통용되게 하는 것입니다:

export HIAPI_API_KEY="your-api-key"

아직 키가 없다면 HiAPI 계정 콘솔에서 먼저 생성한 뒤 진행하세요.

엔드포인트 형태

이 모델은 HiAPI API에서 fibo-2.0/image-to-image로 식별됩니다. 모든 모델 호출은 동일한 기본 URL과 요청 규약을 공유하므로, 한 번 동작하는 호출이 있으면 다른 모델로 바꾸는 일은 주로 모델 식별자와 페이로드 필드를 수정하는 일이 됩니다.

입력 이미지 준비

이미지-투-이미지 요청에는 해석되기를 바라는 URL이 아니라 실제 이미지가 필요합니다. 요청과 함께 업로드하는 로컬 파일로 제공할지, API가 허용하는 참조로 제공할지 미리 정하고, 애플리케이션 코드를 작성하기 전에 형식이 통하는지 확인하세요. 첫 요청에서 가장 흔한 두 가지 실패는 노트북에만 존재하는 경로를 보내는 것과, 엔드포인트가 허용하지 않는 형식의 파일을 보내는 것입니다.

호출을 구성하기 전 실용적 체크리스트:

  • 해당 이미지가 사용 중인 언어로 읽을 수 있는 실제 파일인가.
  • 프롬프트가 키워드 나열이 아니라 원하는 편집을 평이한 언어로 설명하는가.
  • 어떤 파라미터를 보내고 어떤 것을 기본값으로 둘지 명확한가.
  • 요청을 보내는 환경에서 API 키를 찾을 수 있는가.

이것들이 준비되면 요청 자체로 넘어갈 수 있습니다.

실행 가능한 curl 요청 한 줄씩 해부

curl부터 시작하세요. curl은 여러분과 HTTP 요청 사이의 모든 추상화를 제거하므로, 오류가 나면 문제가 요청에 있는지 클라이언트 라이브러리에 있는지 확신할 수 있습니다.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fibo-2.0/image-to-image",
    "prompt": "turn the scene into a soft watercolor illustration, keep the subject and framing",
    "image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
    "n": 1
  }'

아래에서 각 부분의 역할을 하나씩 설명합니다.

요청 라인

-X POST는 메서드를 설정합니다. URL은 HiAPI API 기본 주소에 이미지 생성 경로를 더한 것입니다. 기본 주소는 변수나 설정 값에 두어 여러 곳에 하드코딩하지 마세요. 그러면 나중에 변경할 때 한 곳만 고치면 됩니다.

요청 헤더

Authorization: Bearer $HIAPI_API_KEY는 자격 증명을 전달합니다. 셸이 앞서 내보낸 환경 변수를 확장하므로 키가 명령 기록에 문자 그대로 남지 않습니다. Content-Type: application/json은 API에 요청 본문을 JSON으로 파싱하라고 알립니다. JSON 본문을 보내면서 이 헤더를 빠뜨리는 것은 이해하기 어려운 오류를 일으키는 흔한 원인입니다.

페이로드

model은 fibo-2.0/image-to-image를 식별합니다. prompt는 지시입니다. 입력 이미지가 이미 구조를 담고 있으므로 전체 출력 이미지가 아니라 편집을 설명하세요. image는 엔드포인트가 허용하는 입력 이미지 형태입니다. 직접 내장한다면 파일 내용을 base64로 인코딩한 것입니다. n은 요청할 출력 수를 제어하며, 기본값 유지가 가장 안전한 출발점입니다.

이미지가 크면 셸 명령에 직접 내장하는 것이 번거로워집니다. 먼저 파일로 인코딩해 참조하거나, 다음 절의 Python 방식을 쓰세요. 거기서는 파일을 읽고 인코딩하는 데 한 줄이면 됩니다.

응답 읽기

응답에 완성된 이미지 바이트가 들어 있다고 가정하지 마세요. curl 호출을 실행하고 JSON을 확인하세요. 작업이 완료되었는지 아직 실행 중인지 판단하려면 작업 식별자나 상태 필드를 찾아야 합니다. 파싱 코드를 작성하기 전에 응답 구조를 먼저 캡처하세요. 응답의 형태가 폴링 방법을 결정하기 때문입니다.

요청을 Python으로 옮기기

Python은 요청을 더 유지보수하기 쉽게 만들고, 코드베이스 전체에서 재사용할 수 있는 함수로 감쌀 수 있게 해줍니다. 아래는 동일한 요청을 구현한 경량 클라이언트입니다:

import base64
import os
import time

import requests

BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]


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


def submit_image_edit(image_path: str, prompt: str) -> dict:
    payload = {
        "model": "fibo-2.0/image-to-image",
        "prompt": prompt,
        "image": encode_image(image_path),
        "n": 1,
    }
    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=60,
    )
    response.raise_for_status()
    return response.json()

이 구조를 쓰는 이유

encode_image와 submit_image_edit를 분리하면 파일 처리와 HTTP 처리가 서로 독립되어 각각 테스트하기 쉬워집니다. 임포트 시점에 환경에서 키를 읽으면, 여러 계층을 거친 뒤에야 401이 나는 대신 즉시 실패합니다. timeout을 명시하면 연결이 멈춰 작업 프로세스가 무한정 매달리는 일을 피할 수 있습니다.

응답 본문 처리

raise_for_status()는 HTTP 계층 실패를 응답 본문을 로그로 남기며 잡을 수 있는 예외로 바꿔 줍니다. 이는 오류 객체를 조용히 성공으로 파싱하는 것보다 훨씬 유용합니다. 파싱된 JSON을 받으면 그 안의 작업 식별자를 기록하고, 개발 중에는 전체 응답을 기록해 어떤 필드가 실제로 있는지 확인하세요. 가정을 바탕으로 파서를 작성하지 말고, 실제로 관찰한 응답을 바탕으로 작성하세요.

재사용성 유지

두 가지 작은 개선이 곧 효과를 냅니다. 기본 URL과 모델 이름을 상수로 두어 다른 모델 호출이 같은 클라이언트를 공유하게 하고, 제출 함수가 타입이 지정된 구조(작은 dataclass 또는 알려진 키를 가진 dict)를 반환하게 하여 폴링 코드가 의존할 안정적인 계약을 갖게 하세요.

비동기 생명주기와 폴링 처리

이미지 작업은 순간적으로 끝나지 않습니다. 통합은 제출과 완료를 별개의 두 사건으로 다뤄야 합니다.

1단계: 제출하고 영속화하기

작업을 제출한 뒤 작업 식별자를 영속적인 위치—데이터베이스 행, 큐 메시지, 최소한 로그 한 줄—에 저장하세요. 제출과 완료 사이에 프로세스가 죽으면 기록되지 않은 작업은 잃어버린 작업입니다. 나중에 대조할 수 있도록 식별자를 해당 결과를 소유한 시스템 내 엔티티와 연결하세요.

2단계: 백오프를 동반한 폴링

합리적인 간격으로 작업 상태 엔드포인트를 폴링하세요. 타이트 루프로 상태 엔드포인트를 반복해서 두드리는 것은 자원 낭비이자 가장 흔한 비동기 오류입니다:

def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        job = response.json()
        if job.get("status") in {"succeeded", "failed"}:
            return job
        time.sleep(interval)
        interval = min(interval * 1.5, 10.0)
    raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")

짧은 간격에서 시작해 점차 늘리면 초기 확인의 응답성을 유지하면서 장기간 고빈도 요청을 피할 수 있습니다. 하드 데드라인은 영원히 끝나지 않을 작업을 무한히 기다리는 일을 막습니다.

3단계: 실패를 정상 결과로 다루기

완료된 작업이 반드시 성공한 작업은 아닙니다. 출력을 읽기 전에 상태를 확인하고 실패를 명시적으로 분기 처리하세요. 작업이 반환한 오류 세부 정보를 기록하고, 호출자에게 재시도 가능 신호를 보내고, 재시도가 같은 입력을 재사용할지 새로 생성할지 결정하세요. 클라이언트 측에서 타임아웃된 작업은 서버에서 여전히 실행 중일 수 있으므로 확인 없이 무작정 다시 제출하지 마세요.

4단계: 결과 가져오기와 저장

작업이 성공했다고 보고하면, 그것이 제공하는 출력 참조를 읽어 제때 다운로드하세요. 결과를 장기 보관하려면 참조가 영구히 유효하다고 믿지 말고 자신의 저장소로 복사하세요.

흔한 오류와 해결 방법

대부분의 실패는 몇 가지 예측 가능한 상황으로 분류됩니다. 아래 목록을 순서대로 확인하세요.

인증 실패

401 또는 403은 거의 항상 헤더 오류나 키 누락을 뜻합니다. 헤더가 정확히 Authorization: Bearer <key>인지, Bearer 뒤에 공백이 하나 있는지 확인하고, 환경 변수가 대화형 셸에만이 아니라 요청을 보내는 프로세스에 실제로 설정되어 있는지 확인하세요. 키를 붙여넣을 때 뒤에 붙는 공백이나 불필요한 따옴표가 이 문제의 상당 부분을 차지합니다.

페이로드 형식 오류

400 또는 422는 보통 API가 요청 본문을 해석할 수 없다는 뜻입니다. 세 가지를 순서대로 확인하세요. Content-Type: application/json이 있는지, JSON이 실제로 파싱되는지(끝에 붙은 쉼표가 망가뜨립니다), 필수 필드가 올바른 이름으로 있는지입니다. base64 이미지 데이터를 보낸다면 유효한 base64인지, 기본 파일 형식이 지원되는지 확인하세요. 잘렸거나 이중 인코딩된 문자열은 혼란스러운 검증 오류를 만듭니다.

폴링 오류

작업이 끝나지 않는 것 같으면, 제출 응답이 실제로 반환한 식별자를 사용해 폴링하는지, 올바른 상태 필드를 읽는지 확인하세요. failed 상태를 무시하는 타이트 루프는 멈춘 것처럼 보입니다. 하드 타임아웃을 넣고 관찰한 상태 변화를 기록하세요. 그 로그가 보통 문제를 즉시 드러냅니다.

응답 파싱 함정

결과를 읽을 때 코드가 예외를 던지면 응답 형태를 추측하지 마세요. 먼저 원시 응답 본문을 기록하세요. 흔한 문제로는 참조를 바이트로 착각하기, 성공 시에만 있는 필드를 항상 있는 것으로 다루기, 실패 경로 파서로 성공 응답을 파싱하기 등이 있습니다. 추출 로직은 실제로 본 응답을 바탕으로 만드세요.

빠른 분류 습관

문제가 생기면 먼저 계층을 분리하세요. 같은 페이로드로 curl 명령을 실행하세요. curl은 성공하는데 Python이 실패하면 오류는 클라이언트에 있고, 둘 다 실패하면 오류는 요청에 있습니다. 이 간단한 테스트가 어떤 디버깅 습관보다 시간을 아껴 줍니다.

동작하는 호출과 견고한 폴링 루프가 있으면 fibo-2.0/image-to-image는 신뢰할 수 있는 편집 단계가 됩니다. HiAPI의 모델 페이지에서 시작해 위의 요청을 자신의 이미지에 맞게 적용해 보세요.

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

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

API 문서 보기