HiAPI
Ko
블로그

튜토리얼

GPT Image 2 API 사용법: 텍스트 투 이미지와 이미지 투 이미지 가이드

Nov 3, 2026
抽象液态色块层叠的扁平封面图，深墨底色上流动青瓷绿与石板灰带状图形，用于文生图教程文章。

GPT Image 2 API가 개발자에게 제공하는 것

GPT Image 2 API는 프롬프트로 이미지를 생성하기 위한 통일되고 일관된 인터페이스를 제공합니다. 여러 공급자를 조합하거나 여러 SDK를 유지할 필요 없이 HiAPI.ai에 HTTP 요청 하나를 보내면 이미지 데이터를 돌려받습니다. 마케팅 소재 생성기, 앱 온보딩 일러스트, 사용자 대상 크리에이티브 도구 같은 기능을 만들 때 이 점이 중요합니다. 지연 시간, 가동 시간, 예측 가능한 요청 구조가 모두 핵심이기 때문입니다.

두 가지 생성 모드를 사용하게 됩니다:

  • 텍스트 투 이미지: 프롬프트와 목표 크기를 제공하면 모델이 처음부터 이미지를 생성합니다.
  • 이미지 투 이미지: 프롬프트와 함께 하나 이상의 참조 이미지를 제공하면 모델이 해당 참조 이미지의 안내를 받아 이미지를 생성합니다.

두 모드는 동일한 인증과 응답 구조를 공유하므로, 하나의 호출이 작동하면 두 번째는 완전히 새로운 통합이 아니라 약간의 변경에 불과합니다. 이 가이드에서는 두 변형 중 선택하는 방법, 최소 curl 요청, 참조 이미지 처리, 4K 출력 요청, Python 이식, 그리고 프로덕션 이미지 파이프라인이 조용히 실패하는 것을 방지하는 오류 처리 패턴을 차례로 설명합니다.

안정적인 API 계약 위에 이미지 생성이 필요한 기능을 만든다면, 이 글의 나머지 내용은 제로에서 실행 가능한 요청까지 가는 가장 짧은 경로입니다.

텍스트 투 이미지와 이미지 투 이미지: 변형 선택

코드를 작성하기 전에 제품에 실제로 어떤 변형이 필요한지 먼저 정하세요. 이 선택은 주로 출력을 얼마나 제어하고 싶은지, 그리고 예상 사용자가 얼마나 많은 콘텐츠를 제공해야 하는지에 달려 있습니다.

텍스트 투 이미지를 사용할 때

다음과 같은 경우 텍스트 투 이미지가 적절한 기본 선택입니다:

  • 사용자가 원하는 것을 텍스트로 설명하며 원본 소재가 없는 경우.
  • 플레이스홀더 이미지, 키 비주얼, 또는 고정된 프롬프트 템플릿 기반의 변형을 생성하는 경우.
  • 요청 본문을 가능한 한 단순하게—프롬프트와 크기만—유지하여 요청 크기를 작게, 지연 시간을 예측 가능하게 하고 싶은 경우.

이미지 투 이미지를 사용할 때

출력이 이미 존재하는 콘텐츠에 가까워야 할 때 이미지 투 이미지가 올바른 선택입니다:

  • 업로드된 제품 사진을 스타일 재작성하거나 다시 렌더링하는 경우.
  • 일련의 참조 소재에 일관된 시각적 처리를 적용하는 경우.
  • 구도, 색상, 주제를 안내하여 결과가 기존 브랜드나 장면에 맞도록 하는 경우.

실용적인 규칙

프롬프트만으로 출력이 완전히 결정된다면 텍스트 투 이미지를 사용하세요. 의도의 일부가 텍스트가 아닌 이미지에 존재하고—프롬프트로 설명하면 손실되거나 장황해지거나 신뢰할 수 없는 경우—이미지 투 이미지를 사용하여 참조 이미지를 전달하세요.

흔한 실수는 더 나은 프롬프트로 해결할 수 있는 문제에 이미지 투 이미지를 사용하는 것입니다. 참조 이미지는 업로드 오버헤드를 늘리고 요청 검증 실패 가능성도 높입니다. 텍스트 투 이미지부터 시작하고, 프롬프트로 포착할 수 없는 특정 시각적 속성을 지목할 수 있을 때만 참조 이미지 변형으로 전환하세요.

curl로 첫 번째 텍스트 투 이미지 요청 보내기

curl부터 시작하세요. SDK 동작이라는 변수를 배제하므로, 어딘가 실패할 때 문제가 클라이언트 라이브러리가 아니라 인증이나 요청 본문 구조에 있음을 확신할 수 있습니다.

API 키를 환경 변수로 설정하여 셸 기록이나 소스 관리에 남지 않도록 하세요:

export HIAPI_API_KEY="your_api_key_here"

그런 다음 최소 요청을 보내세요:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

응답에서 확인해야 할 사항:

  1. HTTP 상태 코드. 200은 요청이 수락되고 처리되었음을 의미합니다. 다른 상태 코드라면 무엇이든 변경하기 전에 먼저 오류 응답 본문을 읽으세요.
  2. 인증. 401은 거의 항상 키가 누락되었거나, 형식이 잘못되었거나, 만료되었음을 의미합니다—Authorization 헤더가 Bearer 뒤에 키가 오는 형식인지 확인하세요.
  3. 요청 본문. 400은 보통 특정 필드를 가리킵니다: 매개변수 철자 오류, 모델이 허용하지 않는 크기 문자열, 또는 검증을 통과하지 못한 프롬프트.
  4. 이미지 페이로드. 응답 모드에 따라 가져올 수 있는 URL이나 base64 이미지 데이터를 받게 됩니다. 클라이언트가 나중에 당황하지 않도록 두 가지 모두 처리하세요.

이 호출이 성공하면 세 가지를 동시에 검증한 것입니다: 키가 유효하고, 엔드포인트 경로가 올바르며, JSON 구조가 허용됩니다. 이 가이드의 이후 모든 변경은 이 검증된 기준선에서 시작합니다.

참조 이미지로 출력 안내하기

이미지 투 이미지 요청은 텍스트 투 이미지와 동일한 요청 봉투를 유지하며 참조 이미지 입력을 추가합니다. 프롬프트는 여전히 지시를 담고, 참조 이미지는 시각적 컨텍스트를 담습니다.

요청 본문의 변화는 이제 프롬프트 외에 이미지 데이터를 제공한다는 것입니다. 실제로는 서비스가 가져올 수 있는 URL을 제공하거나 인라인 base64 인코딩 이미지를 제공하며, 통합이 어느 형태를 지원하는지에 달려 있습니다. 다음 규칙을 기억하세요:

  • 프롬프트와 참조 이미지가 일치해야 합니다. 프롬프트가 빨간 제품을 설명하는데 참조 이미지가 파란색이라면 모델은 상충하는 신호를 받습니다. 프롬프트를 참조 이미지와 모순되는 설명이 아니라 참조 이미지에 관한 지시("이 장면을 수채화 스타일로 다시 그려줘")로 작성하세요.
  • 필요한 것만 보내세요. 강력한 참조 이미지 하나가 보통 약한 참조 이미지 여러 개보다 낫습니다. 참조 이미지가 많으면 업로드 볼륨이 늘고 어느 것이 출력을 주도했는지 판단하기 어려워집니다.
  • 요청 볼륨에 주의하세요. base64 인코딩 이미지는 요청 페이로드를 크게 부풀립니다. 큰 사진을 업로드한다면 요청이 느려지거나 거부될 때 여기가 가장 먼저 확인할 곳입니다.
  • 보내기 전에 검증하세요. 이미지가 지원되는 형식인지, 깨끗하게 디코딩되는지 확인하세요. 형식이 잘못된 base64 문자열은 이해하기 어려운 실패를 일으켜 진단에 많은 시간이 걸립니다.

사용 가능한 요청 구조는 다음과 같습니다:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

요청 봉투가 변하지 않으므로 이전에 검증한 curl 호출이 여전히 디버깅 도구입니다: 본문을 바꾸고, 헤더를 유지하며, 응답을 필드별로 비교하세요.

4K 출력 요청하기

출력 해상도는 요청에서 지정되며 모델이 스스로 가정하지 않습니다. 고해상도 출력이 필요하면 size 매개변수로 명시적으로 지정하세요—기본값이 클 것이라고 기대하지 마세요.

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

더 높은 해상도로 전환할 때 확인해야 할 사항:

  • 지원되는 크기 문자열. 크기 값은 모델이 허용하는 범위에 따라 검증됩니다. 거부된 크기는 조용히 다운그레이드되지 않고 400을 반환합니다—따라서 가까운 잘못된 값을 추측하지 말고 필요한 정확한 크기 문자열을 확인하세요.
  • 응답 볼륨. 4K 이미지 데이터는 1K 결과보다 훨씬 큽니다. 응답이 base64나 즉시 다운로드할 URL을 담는다면 메모리와 타임아웃 설정에 이를 위한 여유를 두세요.
  • 지연 시간. 고해상도 생성은 더 오래 걸립니다. 느리지만 성공할 요청이 클라이언트 측에서 타임아웃되지 않도록 관대하게 설정하세요.
  • 비용 모델. 과금은 요청한 출력 크기와 수량에 따라 결정되므로 의식적으로 선택하세요: 기능이 실제로 필요로 하는 해상도로 생성하고, UI가 전체 해상도를 필요로 하지 않는다면 자체 파이프라인에서 다운샘플링하세요. 현재 가격은 웹사이트의 가격 패널을 참조하세요.
  • 신중한 업스케일. 모델이 생성하는 것보다 큰 출력이 필요하다면 생성 후 업스케일은 그 자체의 품질 트레이드오프가 있는 별도 단계입니다. 어느 경로를 택할지 의식적으로 결정하세요.

4K를 배치 작업에 연결하기 전에 잘 알려진 프롬프트로 4K를 먼저 테스트하여 해상도 관련 실패가 인증이나 요청 본문 문제와 혼동되지 않도록 하세요.

요청을 Python으로 이식하기

Python에서 요청을 처음부터 다시 작성하지 마세요. curl에서 이미 검증한 정확한 요청 본문을 이식하고, 응답 처리는 별도로 확인하세요.

import os
import base64
import requests

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

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

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

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

이식에 관한 참고 사항:

  • 키를 환경 변수에 유지하세요, curl과 완전히 동일하게. 절대 인라인으로 넣지 마세요.
  • 명시적 타임아웃을 설정하세요. 이미지 생성은 일반적인 JSON API 호출보다 느립니다; 기본의 짧은 타임아웃을 사용하는 것이 허위 실패의 흔한 원인입니다.
  • 두 가지 응답 모드를 모두 처리하세요. b64_json과 url에 따라 분기 처리하면 코드가 응답 구성에 관계없이 작동합니다.
  • 함수를 재사용하세요. 이를 작은 generate_image(prompt, size) 헬퍼 함수로 감싸면 텍스트 투 이미지와 이미지 투 이미지가 payload의 선택적 image 필드에서만 달라집니다.

payload 딕셔너리는 curl에서 테스트한 바로 그 객체이므로, Python에서 관찰되는 모든 동작 변화는 거의 전부 클라이언트 측—헤더, 인코딩 또는 타임아웃—에서 비롯되며 이는 디버깅 범위를 크게 좁혀줍니다.

오류 처리와 응답 검증

이미지 생성은 본질적으로 실패하기 쉬운 호출입니다: 대부분의 API 엔드포인트보다 느리고, 큰 페이로드를 담으며, 모델 가용성에 의존합니다. 일회성 작업이 아니라 가끔 실패하고 재시도가 필요한 작업으로 취급하세요.

응답 체크리스트

  1. 파싱 전에 상태를 확인하세요. raise_for_status()를 호출하거나 상태 코드를 확인하고 오류 응답 본문을 읽으세요—보통 문제가 된 필드를 지목합니다.
  2. 구조를 검증하세요. 인덱싱하기 전에 data가 존재하고 비어 있지 않은지 확인하세요. data[0]이 반드시 존재한다고 가정하지 마세요.
  3. 이미지 바이트를 확인하세요. 디코딩 후 출력이 비어 있지 않고 유효한 이미지 시그니처로 시작하는지 확인하세요. 0바이트 파일은 한참 후에야 드러나는 조용한 실패입니다.
  4. 요청 ID를 기록하세요. 응답의 요청 식별자를 로그에 보관하면 실패한 생성을 재현 없이 추적할 수 있습니다.

재시도 전략

  • 일시적 실패만 재시도하세요. 타임아웃, 연결 재설정, 5xx 응답은 재시도할 가치가 있습니다. 401이나 400은 매번 동일하게 실패합니다—재시도하지 말고 요청을 수정하세요.
  • 지터를 포함한 지수 백오프를 사용하세요. 짧은 지연에서 시작하여 점진적으로 늘리세요; 지터는 워커 그룹이 동시에 재시도하는 것을 방지합니다.
  • 시도 횟수를 제한하세요. 보통 두세 번의 재시도로 충분합니다. 그 이후에는 사용자에게 오류를 노출하거나 작업을 데드 레터 경로로 보내세요.
  • 멱등하게 만드세요. 재시도가 중복 생성을 일으킬 수 있으므로 결과를 원래 작업 ID와 연결해 저장하여 재시도가 사용자 가시 작업에 이중으로 과금되지 않도록 하세요.

비동기 적합하게 만들기

고해상도 생성은 오래 걸리므로 아키텍처가 허용한다면 요청 스레드를 계속 점유하지 마세요. 작업을 큐에 넣고 호출자에게 작업 ID를 반환하며, 워커가 위의 재시도 전략으로 호출을 수행하도록 하세요. 이렇게 하면 웹 계층이 응답성을 유지하고 느리고 실패하기 쉬운 작업을 재시도 비용이 낮은 곳에 격리할 수 있습니다.

첫 번째 프로덕션 사고 이후가 아니라 첫 번째 작동하는 호출부터 이 검사들을 연결하세요—작은 검증 헬퍼 하나의 비용은 3주 후 빈 이미지 파일을 디버깅하는 것보다 훨씬 적습니다. 인증, 요청 본문 구조, 해상도, 재시도가 모두 확인되면 GPT Image 2 API는 데모용 통합이 아니라 신뢰할 수 있는 빌딩 블록이 됩니다.

관련 글

모든 아티클 보기 →

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

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

API 문서 보기