튜토리얼
HiAPI API를 통해 gpt-image-2.6-sunburst/image-to-image 사용하는 방법: curl 및 Python 실전
참조 이미지 제출, 비동기 작업 폴링, 엔드투엔드 요청 디버깅
이 페이지에서
gpt-image-2.6-sunburst/image-to-image의 적용 시나리오
텍스트-투-이미지는 모델이 프롬프트에 따라 자유롭게 생성한 결과를 줍니다. 이미지-투-이미지는 당신이 이미 가진 소재에서 출발합니다: 엔드포인트에 참조 이미지와 지시를 제공하면 모델이 그 참조 이미지에서 파생된 새 이미지를 생성합니다. HiAPI에서 gpt-image-2.6-sunburst/image-to-image는 이 두 번째 모드 전용 엔드포인트입니다.
소스 이미지 자체가 요구사항의 일부일 때 선택하세요—예를 들어 기존 소재의 스타일을 재디자인하거나, 조명이나 구도를 조정하거나, 제품 이미지에 특정 시각적 처리를 적용하거나, 디자인에서 통제된 변형을 생성할 때입니다. 참조 이미지가 앵커입니다: 피사체, 색상 팔레트, 레이아웃을 담고 있으며, 당신의 프롬프트는 장면을 처음부터 묘사하는 것이 아니라 변환을 설명합니다. 소스 소재가 없고 설명만으로 이미지를 원한다면 텍스트-투-이미지 엔드포인트가 더 간단하고 모델에 더 큰 자유도를 줍니다.
두 가지 실질적 영향이 아래 모든 것을 결정합니다. 첫째, 요청은 준-바이너리 입력(이미지 참조)을 담고 있으며, 이는 요청 본문을 구성하는 방식에 영향을 줍니다. 둘째, 이미지 생성은 즉시 이루어지지 않으므로 이 엔드포인트는 이미지를 인라인으로 반환하지 않고 비동기 작업으로 실행됩니다. 한 번의 블로킹 호출이 아니라 '제출'과 '조회' 두 단계를 계획하세요.
사전 조건 및 인증 설정
첫 요청을 보내기 전에 세 가지가 필요합니다: HiAPI 계정, API 키, 그리고 엔드포인트가 받아들이는 참조 소스 이미지 방식입니다. HiAPI 콘솔에서 키를 생성하고 비밀번호처럼 다루세요—그것은 당신의 계정으로 청구되는 모든 호출을 승인합니다.
키를 Authorization 헤더에 bearer 토큰으로 전달하세요. 소스 파일, 노트북, 커밋 기록에 절대 하드코딩하지 마세요. 셸 테스트를 위해 환경 변수로 내보내고, 애플리케이션 코드에서는 환경(또는 비밀 관리자)에서 읽으세요:
export HIAPI_API_KEY="your_api_key_here"
참조 이미지를 제공하는 방법을 미리 결정하세요. 일반적으로 소재를 임시 위치에 업로드하고 URL을 전달하거나, 요청 본문에 base64 인코딩 데이터로 이미지를 전송할 수 있습니다. URL은 요청을 더 작고 기록하기 쉽게 만듭니다; base64는 별도 호스팅을 없애지만 요청 본문을 부풀립니다. 어느 쪽이든 파일을 엔드포인트가 지원하는 형식으로 유지하고 보내기 전에 크기 제한을 확인하세요. 또한 당신의 계정에 해당하는 HiAPI API 기본 URL을 기록해 두세요—아래 모든 경로에 그것을 접두사로 붙여야 합니다.
curl로 참조 이미지 제출하기
셸에서 먼저 시작하면 실제로 전송되는 내용을 정확히 볼 수 있습니다. 호출 형태는 이미지-투-이미지 엔드포인트에 POST를 보내고, JSON 요청 본문에 참조 이미지와 지시를 담는 것입니다.
curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1
}'
필드별 설명: model은 엔드포인트를 선택합니다; image는 참조 이미지를 담습니다(여기서는 URL, 파일을 호스팅하지 않는다면 base64 데이터 문자열); prompt는 편집 지시로, 피사체를 다시 묘사하는 것이 아니라 변경 사항을 설명해야 합니다; n은 원하는 출력 개수입니다. prompt를 구체적이고 범위가 명확하게 만드세요—참조 이미지와 모순되는 지시는 혼란스러운 결과를 낳기 쉽습니다.
요청을 보내고 응답 본문을 확인하세요. 비동기 엔드포인트의 경우 완성된 이미지를 받지 않습니다; 작업 식별자나 상태 객체를 받습니다. 진행하기 전에 그 응답을 저장하세요—그것이 이후 모든 작업의 핸들입니다. curl -i로 빠르게 확인하면 HTTP 상태 코드도 볼 수 있으며, 이는 인증 문제(제출 시 4xx)와 콘텐츠 문제를 구분하는 가장 빠른 방법입니다.
Python으로 동일한 호출 실행하기
셸 호출이 성공하면 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-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1,
}
resp = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)
curl과의 차이는 기계적입니다: 키는 os.environ에서 오고, 요청 본문은 JSON으로 직렬화된 dict이며, raise_for_status()는 실패한 제출을 조용한 오류 대신 예외로 바꿉니다. 마지막 줄이 중요합니다—대부분의 디버깅 고통은 4xx 응답을 성공으로 착각한 뒤 존재한 적 없는 작업 ID를 폴링하는 데서 비롯됩니다.
바이너리 입력의 경우 파일을 읽고 base64로 인코딩한 뒤 URL 대신 문자열을 image에 넣으세요. 요청 본문의 나머지는 그대로이므로 요청 로직을 바꾸지 않고 방식만 전환할 수 있습니다.
비동기 작업 라이프사이클 처리하기
이미지 생성에는 시간이 걸리므로 엔드포인트는 '먼저 제출 후 폴링' 패턴을 따릅니다. 세 가지 상태를 이해하면 나머지는 기록 작업입니다.
1. 제출하고 작업 캡처하기
POST는 작업 식별자를 반환합니다. 즉시 추출하여 어딘가에 영속화하세요—데이터베이스 행, 큐 메시지, 조회 가능한 로그 줄. 프로세스가 제출과 폴링 사이에 충돌하면 그 식별자가 이미 비용을 지불한 작업을 복구하는 유일한 방법입니다.
2. 완료될 때까지 폴링하기
작업 ID로 상태 엔드포인트를 고정 간격으로 폴링하세요. 보수적으로 시작하세요—검사마다 몇 초 간격—긴 작업에는 점진적으로 백오프하여 API를 강타하지 않도록 하세요. 종료 상태에서 멈추세요: 성공, 실패, 또는 당신이 설정한 타임아웃. 절대 타이트 루프로 폴링하지 마세요.
import time
def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"{base_url}/v1/images/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
if data["status"] in ("succeeded", "failed"):
return data
time.sleep(interval)
interval = min(interval * 1.5, 15)
raise TimeoutError(f"job {job_id} not finished in time")
3. 결과 가져오고 저장하기
성공하면 응답이 생성된 이미지를 가리킵니다. URL이 임시라면 제때 다운로드하여 당신이 통제하는 이름으로 자신의 스토리지에 쓰세요, 그러면 다운스트림 소비자가 임시 링크에 의존하지 않게 됩니다. 작업 ID를 저장된 소재와 함께 기록하세요—가장 저렴한 디버깅 보조 수단입니다.
프로덕션에서는 요청 핸들러가 아니라 백그라운드 워커가 폴링을 구동해야 합니다. 전체 이미지 생성 시간 동안 블로킹하는 웹 요청은 취약하고 연결을 불필요하게 점유합니다.
흔한 오류 및 해결 방법
호출이 실패하면 이 목록을 위에서 아래로 확인하세요; 첫 항목이 대부분의 문제를 잡아냅니다.
제출 시 401 / 403
인증 문제입니다. 키가 Authorization 헤더에 있는지, Bearer 스킴을 사용하는지, 복사-붙여넣기로 인한 잡다한 공백이나 개행이 없는지 확인하세요. 요청을 실행하는 셸이나 프로세스에서 환경 변수가 실제로 설정되어 있는지 확인하세요.
요청 본문의 400 / 422
요청 본문이 잘못되었거나 특정 필드가 틀렸습니다. 흔한 원인: 수동 curl 문자열로 인한 JSON 구문 오류, image 값이 접근 가능한 URL도 유효한 base64도 아님, prompt 누락, 또는 지원되지 않는 이미지 형식. JSON을 로컬에서 검증하고 참조 이미지가 브라우저에서 실제로 로드되는지 확인하세요.
모델 또는 경로의 404
경로나 모델 이름의 철자 오류입니다. 모델 식별자는 정확한 문자열입니다—gpt-image-2.6-sunburst/image-to-image는 텍스트-투-이미지 변형과 다르며 대소문자를 구분합니다.
타임아웃 및 폴링 중단
느린 작업과 잘못된 작업을 구분하세요. 모든 HTTP 호출에 timeout을 설정하고, 자신만의 전체 데드라인을 정하며, 포기할 때 마지막으로 관찰한 작업 상태를 기록하세요. 작업이 자주 데드라인을 넘으면 타이트한 재시도 루프로 바꾸지 말고 데드라인을 늘리세요.
출력이 비어 있거나 사용 불가
작업은 성공했지만 이미지가 원하는 것이 아닙니다. 이는 보통 프롬프트 문제입니다: 지시가 너무 모호하거나 참조 이미지와 충돌합니다. 편집 지시에서 무엇이 변해야 하고 무엇이 반드시 그대로여야 하는지 더 구체적으로 명시하세요.
이미지-투-이미지 파이프라인의 프로덕션 권장 사항
프로토타입이 돌아가면 남은 일은 신뢰성과 예측 가능성입니다.
- 재시도 가능한 오류만 재시도하세요. 5xx와 네트워크 오류로 인한 제출 실패에는 지수 백오프 재시도를 사용하세요; 4xx를 맹목적으로 재시도하지 마세요, 그것은 다시 실패할 뿐입니다. 작업 키를 자신의 요청 ID에 바인딩하여 멱등성을 직접 추적하면 재시도가 작업을 중복시키지 않습니다.
- 제출과 폴링을 분리하세요. 제출과 폴링을 다른 워커나 단계에 배치하세요. 이렇게 하면 API 지연이 생성 시간과 독립적이 되고 폴링을 독립적으로 확장할 수 있습니다.
- 자신의 스토리지를 통제하세요. 작업이 완료되면 즉시 결과를 자신의 버킷에 다운로드하세요. 반환된 URL은 임시 링크로 취급하세요.
- 프롬프트를 버전 관리하세요. 프롬프트는 프로덕션 자산입니다. 프롬프트, 참조 이미지, 작업 ID를 각 출력과 함께 저장하면 몇 달 후에도 결과를 재현하거나 설명할 수 있습니다.
- 지연과 비용을 주시하세요. 이미지 작업은 출력 기준으로 청구되므로 사용자당 동시성을 제한하고 작업별로 사용량을 기록하세요. 제출부터 소재 저장까지의 p95 지연을 모니터링하세요—그것이 사용자가 실제로 체감하는 숫자입니다.
요청 형태와 라이프사이클이 확정되면 남은 것은 일상적인 엔지니어링입니다. HiAPI 문서에서 모델 세부 정보를 찾고, 거기서 엔드포인트를 당신의 파이프라인에 연결하세요.