튜토리얼
HiAPI API를 통해 gpt-image-2.6-flare/image-to-image를 호출하는 방법: curl과 Python
참조 이미지 업로드, 동기와 비동기 요청, 그리고 동작하는 호출 디버깅
이 페이지에서
이 엔드포인트가 하는 일과 image-to-image를 사용해야 할 때
텍스트-이미지 모델은 장면을 처음부터 창조하는 데 능숙하지만, 많은 프로덕션 작업은 이미 존재하는 이미지에서 시작합니다. gpt-image-2.6-flare/image-to-image는 HiAPI가 이런 작업을 위해 제공하는 엔드포인트입니다. 참조 이미지와 프롬프트를 보내면, 모델은 지시를 따르면서도 참조 이미지에 단단히 고정된 변환된 이미지를 반환합니다.
대표적인 사용 사례는 다음과 같습니다.
- 스타일 전이 및 재그리기 — 제품 사진을 스타일화된 일러스트로 바꾸거나, 사진을 다른 시각 언어로 다시 그립니다.
- 편집 및 보정 — 다시 촬영하지 않고도 기존 소재의 조명, 배경 또는 구도를 조정합니다.
- 변형 생성 — 기본 디자인에서 여러 시각적 변형을 만들어 A/B 테스트나 창의적 탐색에 활용합니다.
- 소재 적응 — 참조 이미지의 핵심 피사체를 유지하면서 크기를 조정하거나 다양한 채널에 맞게 재구성합니다.
작업이 "무언가를 묘사하고 이미지를 얻는 것"이라면 텍스트-이미지가 더 간단한 선택입니다. 출력이 특정 입력 이미지에서 분명히 파생되어야 할 때만 image-to-image를 사용해야 합니다. 그 참조 이미지가 바로 이 호출의 존재 이유이기 때문입니다. 이 글의 나머지 부분에서는 실제 요청을 처음부터 끝까지 구축합니다. 먼저 curl로 동작을 증명한 뒤 Python으로 작성하여 서비스에 연결할 수 있게 합니다.
사전 요구 사항과 요청 구조
이 엔드포인트를 호출하기 전에 다음 조건이 준비되어 있는지 확인하세요.
- HiAPI 계정과 API key. key는 bearer token 형태로
Authorization요청 헤더에 담겨 전송됩니다. 소스 저장소에 커밋하지 말고 환경 변수(예:HIAPI_API_KEY)에서 불러오세요. - 모델 id.
gpt-image-2.6-flare/image-to-image를 정확히 사용하세요. 모델 id는 대소문자를 구분하며 슬래시도 식별자의 일부입니다. - 엔드포인트 경로. 이미지 생성은 HiAPI API 호스트의 이미지 생성 라우트 아래에 있습니다. 예전 코드 조각에서 본 호스트를 하드코딩하지 말고, 모델 페이지에서 현재의 베이스 URL과 경로를 확인하세요.
- 참조 이미지 파일은 일반적인 형식(PNG 또는 JPEG가 안전한 기본값)을 사용하세요. 크기를 합리적인 범위로 유지하세요. 너무 큰 파일은 업로드를 느리게 하고 요청 제한을 유발할 수 있습니다.
gpt-image-2.6-flare/image-to-image 요청은 세 가지 핵심 부분으로 구성됩니다.
- 모델 선택자 — HiAPI에게 요청을 어느 모델로 라우팅할지 알려줍니다.
- 프롬프트(prompt) — 원하는 변환을 설명하는 텍스트 지시입니다. 선택 사항이 아닙니다. 프롬프트가 편집을 이끄는 핵심입니다.
- 참조 이미지 — 모델이 기반으로 처리해야 할 입력 이미지입니다. 전달 방식은 요청 방식에 따라 달라집니다(다음 섹션 참조).
그 외에는 해당 모델의 HiAPI 모델 페이지에 문서화된 매개변수만 전달해야 합니다. 필드 이름이 "맞아 보인다"는 이유로 임의로 만들어 넣고 있다면 잠시 멈추고 문서를 확인하세요. 알 수 없는 매개변수는 혼란스러운 4xx 오류의 흔한 원인입니다.
참조 이미지를 전달하는 방법
개념적으로 참조 이미지는 요청 본문의 또 다른 입력 필드일 뿐이지만, 그 부피 때문에 특별합니다. API에 바이트를 전달하는 실용적인 방법은 두 가지이며, 이 선택은 API 자체보다 클라이언트 코드에 훨씬 큰 영향을 미칩니다.
방식 A: 요청 본문에 인라인
작은 이미지는 보통 base64 인코딩 문자열 형태로 JSON 페이로드에 직접 삽입할 수 있습니다. 파일을 읽고 인코딩한 뒤 문자열을 요청의 image 필드에 넣습니다. 모든 것이 하나의 요청에 담기며, 썸네일, 아이콘, 테스트 픽스처에 매우 적합합니다.
대가는 다음과 같습니다. base64는 페이로드를 약 3분의 1 부풀리고, JSON 인코더가 매우 긴 문자열을 처리하지 못할 수 있으며, 로그에서 수 메가바이트의 요청 본문을 디버깅하는 것은 매우 고통스럽습니다. 인라인은 편의성을 위한 것이지 대형 소재를 위한 것이 아닙니다.
방식 B: 먼저 업로드하고 URL로 참조
작은 이미지가 아닌 모든 것에는 파일을 먼저 직접 제어하는 저장소에 업로드한 뒤, 그 URL을 참조로 전달하세요. 요청 본문이 작게 유지되고, 재시도 비용이 낮으며, 같은 이미지를 매번 다시 업로드하지 않고 여러 호출에서 재사용할 수 있습니다.
URL을 사용할 때 주의할 점이 몇 가지 있습니다.
- URL은 API가 공개적으로 접근 가능해야 합니다. 인증 뒤에 있거나, localhost이거나, 요청 중간에 만료되는 서명 링크여서는 안 됩니다.
- 모델이 허용하는 콘텐츠 유형을 사용하세요. URL이 이미지 대신 HTML을 반환하면 검증이 실패합니다.
- 저장소와 HiAPI 요청 간 로그를 연관시키기 위해 안정적인 파일 이름을 우선 사용하세요.
어느 방식을 선택하든 참조 이미지와 프롬프트는 같은 요청에 전달됩니다. API는 별도의 "먼저 업로드 후 생성" 핸드셰이크를 요구하지 않습니다. 모델 호출은 하나의 논리적 작업입니다.
동기 호출 vs 비동기 호출
이미지 생성에는 시간이 걸리기 때문에 많은 이미지 API가 동기 방식과 함께 비동기 작업 방식을 제공합니다. 여기에도 같은 트레이드오프가 적용됩니다.
동기
요청을 보내고 이미지가 반환될 때까지 연결을 열어 둡니다. 코드는 한 줄기입니다. 요청을 구성하고, POST하고, 응답을 읽으면 끝입니다.
다음과 같은 경우 동기 호출을 사용하세요.
- 프로토타이핑이나 디버깅 중이며 한 단계에서 전체 결과를 보고 싶습니다.
- 요청이 일정 시간 차단을 허용하는 환경(CLI 도구, 백그라운드 worker)에서 실행됩니다.
- 폴링 로직 없이 최대한 단순한 클라이언트를 원합니다.
단점은 생성이 오래 걸리면 연결을 오래 유지해야 하고, 클라이언트와 API 사이의 프록시나 로드 밸런서가 자체 타임아웃을 적용할 수 있다는 것입니다.
비동기
요청을 작업으로 제출하고, 즉시 작업 식별자를 받은 뒤, 완료될 때까지 폴링(또는 콜백 수신)합니다. 클라이언트에는 제출, 대기, 결과 가져오기, 실패 처리 등의 작은 상태 머신이 필요합니다.
다음과 같은 경우 비동기 호출을 사용하세요.
- 사용자 대상 트래픽을 처리하며 요청 스레드를 차단할 여유가 없습니다.
- 많은 이미지를 일괄 생성하고 병렬로 분배해 결과를 수집하려 합니다.
- 인프라에 직접 제어할 수 없는 짧은 요청 타임아웃이 있습니다.
선택 방법: 누군가가 웹 요청에서 결과를 기다리고 있다면 비동기를 사용하세요. 스크립트나 worker가 오프라인에서 대기한다면 동기가 더 단순하고 문제없습니다. 과도하게 설계하지 마세요. 먼저 동기로 시작하고, 실제 타임아웃이나 동시성 제한이 강제할 때 비동기로 전환하세요.
이 글의 나머지 부분은 모든 단계가 명확히 보이도록 동기 방식을 사용하지만, 구축한 요청 본문은 두 모드에서 동일합니다. 주변 파이프라인만 다릅니다.
동작하는 curl 요청
터미널에서 이 호출을 구성해 봅시다. 먼저 key를 설정하세요.
export HIAPI_API_KEY="your-api-key-here"
1단계: 참조 이미지 준비
실패 시 원인이 모호하지 않도록 작고 의심의 여지가 없는 이미지로 시작하세요.
ls -lh reference.png
file reference.png
file은 PNG image data 또는 JPEG image data를 보고해야 합니다. 다른 것을 보고하면 계속하기 전에 먼저 수정하세요.
2단계: 요청 전송
요청은 이미지 생성 엔드포인트로 보내는 POST이며, JSON 본문에 모델, 프롬프트, 참조 이미지가 포함됩니다. 선택한 업로드 방식에 따라 image 필드는 URL이거나 base64 문자열입니다.
curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png"
}'
이 매개변수들에 대해:
-sS는 진행 표시줄을 숨기되 오류는 표시합니다. 스크립트에 적합합니다.Authorization: Bearer $HIAPI_API_KEY는 키가 명령 자체에 나타나지 않게 합니다.$HIAPI_BASE_URL은 모델 페이지에서 설정하세요. 호스트를 추측하지 마세요.- 여기서
image필드는 URL 방식을 사용합니다. 인라인 이미지의 경우 base64 문자열로 바꾸세요.
3단계: 응답 읽기
응답 헤더를 포함하려면 -i를, 상태 코드를 출력하려면 -w '\nHTTP %{http_code}\n'을 추가하세요. 성공한 호출은 이미지(또는 응답 형식에 따라 이미지 링크)와 메타데이터를 반환합니다. 실패하면 4xx 또는 5xx 상태 코드와 JSON 오류 본문을 받습니다. 다른 것을 바꾸기 전에 message 필드를 먼저 읽으세요.
4단계: 출력을 파일로 파이프
깔끔한 파일을 얻으려면 stdout을 파일로 리디렉션하고 다시 file로 확인하세요. 응답이 URL을 포함한 JSON이면 해당 URL을 추출하고 두 번째 curl로 다운로드하세요. 자동화에 연결하기 전에 다운로드한 바이트가 실제로 이미지인지 항상 검증하세요.
같은 요청의 Python 버전
curl 기준선은 Python으로 바로 옮길 수 있습니다. 이 예제는 표준 라이브러리와 requests만 사용합니다.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
응답 처리
응답 형식은 다양합니다. 이미지를 직접 포함할 수도 있고 URL을 포함할 수도 있습니다. 두 경우를 통합하는 작은 헬퍼 함수를 작성하면 다운스트림 코드가 어느 쪽인지 신경 쓰지 않아도 됩니다.
def extract_image(data):
if "url" in data:
return requests.get(data["url"], timeout=60).content
if "image" in data:
import base64
return base64.b64decode(data["image"])
raise ValueError(f"Unexpected response shape: {list(data)}")
오류 처리
raise_for_status()가 유일한 오류 경로가 되게 하지 마세요. 호출을 감싸고 API의 오류 메시지를 노출하세요.
try:
response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
image_bytes = extract_image(response.json())
except requests.HTTPError as e:
print("HTTP", e.response.status_code, e.response.text)
raise
except requests.Timeout:
print("Request timed out; consider the async job route instead")
raise
비동기 변형
비동기 방식의 경우 같은 페이로드로 작업을 제출하고, 응답에서 작업 id를 읽은 뒤, 짧게 대기하며 작업 상태 엔드포인트를 폴링합니다. 폴링 횟수에 상한을 두고 예산 소진을 실패로 간주하세요. 요청 핸들러에서 무한 폴링하는 일은 절대 없어야 합니다.
흔한 오류 진단
대부분의 실패는 몇 가지 유형으로 나뉩니다. 이 체크리스트를 순서대로 확인하세요. 각 단계는 하나의 변수를 격리합니다.
인증 오류(401 / 403)
HIAPI_API_KEY가 실제로 셸이나 프로세스에 설정되어 있나요?echo $HIAPI_API_KEY가 값을 출력해야 합니다.- 헤더가 정확히
Authorization: Bearer <key>인가요? 대문자 A, 대문자 B, 공백 하나입니다. - key가 취소되거나 교체되었나요? 다시 생성하고 최소 요청으로 재시도하세요.
잘못된 참조 이미지 페이로드
가장 흔한 실패이며 대개 모델의 잘못이 아닙니다.
- URL 접근 불가: 다른 네트워크의 브라우저에서 이미지 URL을 여세요. 404가 나거나 로그인 페이지로 리디렉션되면 API도 접근할 수 없습니다.
- 잘못된 콘텐츠 유형: HTML이나 JSON을 반환하는 URL은 거부됩니다.
curl -I <url>로 응답이Content-Type: image/...인지 확인하세요. - 파일 손상 또는 읽기 불가: 로컬에서
file reference.png를 실행하세요. base64 문자열을 디코딩한 바이트가 원본 파일과 일치하는지 검증하세요. - 파일이 너무 큼: 모델 페이지에 문서화된 크기 제한을 확인하고 재시도 전에 크기를 줄이세요.
매개변수 형식 오류
- 모델 id 오타:
gpt-image-2.6-flare/image-to-image는 슬래시를 포함해 정확히 일치해야 합니다. - 프롬프트 누락: 텍스트 지시는 필수이며 생략할 수 없습니다.
- 불필요한 필드: 문서에서 찾을 수 없는 매개변수는 제거하세요. 알 수 없는 키는 종종 4xx를 유발합니다.
- JSON 구문: 전송 전에
jq . <<< "$BODY"로 요청 본문을 검증하세요.
타임아웃
이미지가 반환되기 전에 요청이 끊긴다면 연결이 너무 오래 유지된 것입니다. 프롬프트를 줄이고, 참조 이미지를 축소하고, 클라이언트 타임아웃을 늘리세요. 문제가 계속되면 비동기 작업 방식으로 전환하세요. 긴 생성 작업은 바로 비동기가 필요한 영역입니다.
디버깅 전략
시도할 때마다 변수는 하나만 바꾸세요. 아주 작고 확실한 참조 이미지와 프롬프트 한 문장으로 시작해 파이프라인이 동작함을 증명한 뒤 실제 입력을 점진적으로 도입하세요. 실패할 때마다 전체 응답 본문을 기록하세요. message 필드는 보통 요청에서 무엇이 잘못되었는지 직접 알려줍니다.
파이프라인에 연결하기
기준선이 동작하면 몇 가지 습관을 들여 gpt-image-2.6-flare/image-to-image를 프로덕션 환경에서 안정적으로 유지할 수 있습니다.
호출 전 입력 검증. 참조 이미지가 지원되는 형식이고 크기 제한 내인지 확인하고, URL이라면 접근 가능한지도 확인하세요. 실패한 왕복에 비용을 지불하는 대신 자기 경계에서 잘못된 입력을 거부하세요.
호출 후 출력 검증. 응답이 섞여 들어온 HTML 오류 페이지가 아니라 실제 이미지 바이트(매직 넘버 확인)를 포함하는지 확인하세요. 저렴한 헤더 검사 하나가 다운스트림의 많은 혼란스러운 디버깅을 줄여 줍니다.
백오프로 재시도하되 올바른 오류에만. 일시적 5xx와 네트워크 타임아웃은 지터를 더한 지수 백오프로 재시도할 가치가 있습니다. 잘못된 매개변수로 인한 4xx 오류는 매번 똑같이 실패하므로 재시도하지 말고 요청을 수정하세요.
사용자 대상 작업에는 비동기를 우선. 누군가 페이지에서 기다리고 있다면 작업을 제출하고 클라이언트에서 폴링하세요. 긴 생성 작업을 위해 웹 요청을 열어 두지 마세요.
모델 id를 설정에 보관. 모델 id는 시간이 지나면 바뀝니다. 단일 설정 지점에서 읽게 하여 모델 교체가 전역 검색-바꾸기가 아니라 한 줄 수정이 되게 하세요.
다른 HiAPI 모델과 조합. 이 엔드포인트는 텍스트-이미지와 자연스럽게 어울려 하이브리드 흐름(기본 이미지 생성 후 편집)을 구성할 수 있고, 파이프라인에 필요하면 업스케일이나 배경 제거 단계와도 조합할 수 있습니다. 모든 것이 동일한 HiAPI 인터페이스와 인증을 거치므로 단계를 추가하는 것은 같은 key로 한 번 더 호출하는 것일 뿐입니다.
curl 기준선에서 시작해 Python으로 이식하고, 트래픽이 요구할 때 비동기로 전환하세요. 모델 페이지에서 현재의 요청 매개변수와 제한을 제공합니다. 필드 이름이나 크기 상한을 가정하기 전에 먼저 그곳을 확인하세요.