작성자 노트: 이미 APIYI에서 Responses의 image_generation으로 ‘대화하면서 이미지 생성’을 구현한 개발자는 독립 Images API로 마이그레이션한 뒤에도 이 글의 방법으로 연속 이미지 수정을 유지할 수 있어요.
결론부터 말하면: 이미지 생성 부분만 마이그레이션하면 되고, 기존 텍스트 대화는 건드릴 필요가 없어요. 예전에는 previous_response_id로 암묵적으로 이어 붙였던 ‘이전 이미지’를 이제는 애플리케이션이 직접 저장하고, 수정할 때마다 명시적으로 선택해 원본 이미지로 POST /v1/images/edits에 업로드해야 해요. 이렇게 하면 다중 턴 이미지 수정 효과는 그대로이고, 달라지는 것은 ‘이전 이미지’를 누가 기억하느냐뿐이에요.
이 결론의 전제는 APIYI가 2026-11-21 22:30(베이징 시간)에 게시한 문서 업데이트예요. 공식 중계 이미지 모델 5종의 권장 경로가 두 개의 독립 이미지 엔드포인트로 바뀌었어요. OpenAI가 Responses를 중단한 것은 아니며, 사이트 내 텍스트 대화도 평소처럼 사용할 수 있어요. 아래의 모든 인터페이스, 필드, 과금 기준은 APIYI apiyi.com 문서와 OpenAI 공식 이미지 생성 가이드에서 가져왔어요. 코드는 문서 예시일 뿐 실제 테스트 결과를 뜻하지 않아요.

GPT Image API 마이그레이션 지식 맵과 인덱스
전체 마이그레이션은 네 단계로 진행되며, 각 단계의 출력이 다음 단계의 입력이 됩니다.
기존 호출 식별 및 라우팅 분류 (1절)
└─> 출력: 각 요청이 대화, generations, edits 중 어디로 가야 하는지
첫 이미지 생성 및 저장 (2.1절)
└─> 출력: 검증된 v1.png + 에셋 기록
선택한 원본 이미지를 편집 인터페이스에 전달 (2.2절)
└─> 출력: v2.png + parent_asset_id 연결
검수 및 정산 확인 (3절)
└─> 출력: 사용 가능한 이미지 목록 + 검수 이미지별 비용

| 단계 | 의존 대상 | 이 순서인 이유 | 목표 |
|---|---|---|---|
| 1 라우팅 분류 | 기존 코드의 호출 목록 | 어디를 고쳐야 할지 먼저 정해야 텍스트 대화를 잘못 건드리지 않음 | 이미지 생성 요청만 Images API로 전환 |
| 2.1 첫 이미지 생성 | 1단계에서 정한 generations 라우트 | 이후 이미지 편집에는 실제로 저장된 원본 이미지가 필요 | 검증된 v1을 확보해 저장 |
| 2.2 이미지 편집 계속 | 2.1단계에서 저장한 v1 파일 | 독립 엔드포인트는 previous_response_id를 인식하지 않고 업로드한 이미지만 인식 |
v2 확보 및 부모-자식 관계 기록 |
| 3 검수 및 정산 확인 | 2단계의 이미지와 콘솔 로그 | 검수를 통과한 이미지만 비용 산정 기준에 포함 | 납품 가능한 이미지 + 설명 가능한 청구 내역 |
읽는 순서는 이렇게 추천해요: 1절은 꼭 읽고, 2절은 코드 순서대로 따라 하세요. 3절은 출시 전이나 연결이 끊기거나 청구서가 의문일 때 참고하면 됩니다.
To Know: GPT Image API 마이그레이션 용어
| 용어 | 간단한 설명 |
|---|---|
| 공식 중계 | APIYI가 제공하는 공식 전달 채널 모델. 이 글에서는 다섯 가지 이미지 모델 ID를 뜻함 |
| image_generation | Responses API의 이미지 생성 도구. 기존 링크는 이를 통해 대화와 동시에 이미지를 생성 |
| previous_response_id | Responses에서 이전 턴의 컨텍스트를 이어가는 파라미터. 독립 Images 요청은 받지 않음 |
| multipart | 폼 업로드 형식. /images/edits에서 실제 이미지 바이너리를 전송할 때 사용 |
| b64_json | 독립 이미지 엔드포인트가 이미지를 반환하는 필드. 내용은 base64로 인코딩된 이미지 |
| parent_asset_id | 애플리케이션이 직접 기록하는 “이 이미지가 어느 이미지에서 수정되었는지” 연결 필드 |
1 Responses에서 마이그레이션이 필요한 GPT Image API 호출
1.1 GPT Image API 11/21 업데이트 범위와 다섯 가지 공식 중계 모델
이번 문서 업데이트는 다음 다섯 개의 공식 중계 모델 ID를 다뤄요:
gpt-image-2.6-sunburstgpt-image-2.6-flaregpt-image-2.5-sunburstgpt-image-2.5-flaregpt-image-2
대응하는 두 개의 독립 이미지 엔드포인트는 각각 POST /v1/images/generations(JSON 요청 본문)와 POST /v1/images/edits(multipart 폼)예요. APIYI는 Responses의 image_generation 경로로 계속 이미지를 생성하는 것을 권장하지 않아요. 이유는 두 가지예요: 공급이 불안정하고, 추가 도구 비용이 발생하기 때문이에요. 또한 Chat Completions는 이 다섯 가지 공식 중계 이미지 모델로 이미지를 생성하는 것을 지원하지 않아요. 기존 코드에 이런 사용법이 있다면 함께 마이그레이션 목록에 넣어야 해요.
참고로 이번 조정은 이미지 생성에만 영향을 줘요. OpenAI가 Responses를 중단한 것도 아니고, APIYI 사이트 내 텍스트 대화도 중단되지 않았어요. 그래서 마이그레이션 범위는 “요청에서 이미지 도구나 이미지 모델을 호출한” 코드로만 한정돼요. 다섯 모델 중 무엇을 고를지는 별개의 주제라서 APIYI apiyi.com 고객센터의 모델 선택 글을 참고해 주세요. 이 글에서는 다루지 않아요.
1.2 GPT Image API 텍스트 대화, 첫 이미지 생성, 이어서 수정하기의 라우팅
APIYI FAQ에서 제안하는 조합은 이래요: 대화 모델이 사용자 의도를 판단하고, 애플리케이션이 Images API를 별도로 호출하며 이미지를 직접 관리하는 방식이에요. 이 방식대로라면 기존에 Responses 요청 하나가 처리하던 세 가지 일을 세 개의 라우트로 나눌 수 있어요:
| 사용자 의도 | 새 라우트 | 요청 형식 | 이미지 소스 |
|---|---|---|---|
| 순수 텍스트 채팅, Q&A | 기존 텍스트 대화 인터페이스 유지 | 변경 없음 | 없음 |
| 첫 이미지 생성 | POST /v1/images/generations |
JSON | 프롬프트만 |
| 특정 이미지에서 계속 수정 | POST /v1/images/edits |
multipart | 앱이 업로드한 선택된 원본 이미지 |
네이티브 Responses에서는 이미지 수정 이어가기를 previous_response_id로 구현할 수 있고, 이미지를 직접 전달할 수도 있어요. 독립적인 Images 요청은 previous_response_id를 받지 않기 때문에 “다중 턴 이미지 수정”을 애플리케이션이 직접 관리해야 하는 거예요. 모델이 이전 이미지를 대신 기억해 주지 않으니, 그 이미지 파일을 직접 넘겨야 해요.
사용자가 “조금 더 빨갛게”라고 말했는데 세션에 v1, v2, v3 여러 버전이 있다면 앱은 어느 버전을 말하는지 알 수 없어요. 이럴 때는 추측하지 말고 먼저 사용자에게 확인해야 해요. 기본값으로 최신 버전을 쓰는 게 편해 보이지만, 사용자가 사실 v2로 돌아가 다시 수정하고 싶었던 경우라면 불필요하게 한 번 더 과금되고 사용자도 헷갈리게 돼요.
응답 파싱도 함께 바꿔야 해요:

| 경로 | 응답에서 이미지가 있는 위치 | 컨텍스트 이어가는 방식 |
|---|---|---|
| Responses + image_generation | output에서 type=image_generation_call인 항목의 result |
previous_response_id 또는 이미지 전달 |
| 독립 Images API | data[0].b64_json |
앱이 선택한 원본 이미지 업로드 |
2 GPT Image API로 이전 이미지를 이어서 수정하는 방법
아래에서는 두 라운드로 구성된 예시를 통해 전체 흐름을 살펴볼게요. 첫 번째 라운드에서는 파란색 머그컵을 생성하고, 두 번째 라운드에서는 컵 몸통만 벽돌색으로 바꿔요. 파라미터는 APIYI 문서 예시를 그대로 따라요: 모델 gpt-image-2.5-sunburst, 크기 1024x1024, quality=medium, output_format=png. 토큰은 환경 변수 APIYI_KEY에서 읽어 Bearer 방식으로 전달해요.
2.1 GPT Image API로 파란색 머그컵 PNG 생성 및 검증
첫 번째 라운드에서는 generations 엔드포인트를 호출해요. 프롬프트에는 밝은 회색 배경, 중앙에 놓인 파란색 세라믹 머그컵, 오른쪽을 향한 손잡이, 부드러운 측광, 화면에 글자 없음이라는 내용을 담았어요. 응답을 받은 뒤에는 다음 순서로 처리해요:
raise_for_status()를 호출해서 HTTP 레벨의 실패를 먼저 걸러내요.b64_json에 대해 엄격한 base64 디코딩을 수행하고, 풀리지 않으면 실패로 간주해요.- Pillow로 열고
load()를 호출해서 파일이 실제로 이미지로 디코딩되는지 확인해요. - 포맷이 PNG이고 크기가 1024×1024인지 확인한 다음
v1.png로 저장해요. - 애플리케이션에 이 자산을 등록하고, 이후 이미지 수정 시 여기서 원본을 가져와요.
3단계는 절대 생략하면 안 돼요. open()은 파일 헤더만 읽을 뿐이고, 이미지 데이터가 잘렸는지 여부는 load()를 호출해야 드러나거든요.
2.2 GPT Image API로 선택한 원본 이미지 업로드, 컵 몸통만 벽돌색으로 변경
2라운드에서는 edits 엔드포인트를 호출해요. data에는 model, prompt, size, quality, output_format을 담고, files에는 image[] 필드로 v1.png의 실제 바이너리를 업로드해요. 프롬프트의 의미는 이렇게요. 컵 몸통만 벽돌색으로 바꾸고, 컵 모양·손잡이·구도·조명·배경은 모두 그대로 유지하라는 뜻이에요.
이 단계에는 자주 실수하는 지점이 몇 가지 있어요:
response_format을 전달하지 마세요.Content-Type을 직접 손으로 쓰지 마세요. requests가 boundary가 포함된 멀티파트 헤더를 자동으로 생성하는데, 직접 쓰면 오히려 boundary가 사라져요.- base64 문자열을 파일로 업로드하면 안 돼요. 업로드하는 것은 반드시 이미지의 원시 바이트여야 해요.
수정이 끝나면 같은 방식으로 디코딩·검증하고 v2.png로 저장해요. v1은 남겨두고, 에셋 레코드에 parent_asset_id = v1를 적어요. 이 부모-자식 관계가 바로 새 아키텍처에서의 “멀티턴 컨텍스트”예요. 그리고 이건 생성형 편집이라서, 모델이 다른 영역은 최대한 보존하려고 하지만 컵 몸통 외의 픽셀이 하나하나 동일하다고 보장하지는 않아요.
다음은 최소 완성 예시예요(문서 예시이며 이 글에서 실측하지는 않았어요):
import base64
import io
import os
import uuid
import requests
from PIL import Image
BASE_URL = "https://api.apiyi.com/v1" # APIYI 통합 엔드포인트
API_KEY = os.environ["APIYI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
MODEL = "gpt-image-2.5-sunburst"
SIZE = "1024x1024"
# 중간 수준 타임아웃 예시; 네트워크와 화질 설정에 맞게 조정하세요. 자동 재시도 없음.
TIMEOUT = (10, 360)
assets = {} # asset_id -> {"path": ..., "parent_asset_id": ...}
def decode_and_check(resp, path):
resp.raise_for_status()
item = resp.json()["data"][0]
b64 = item.get("b64_json")
if not b64:
raise ValueError("no b64_json in response, check body before any resend")
raw = base64.b64decode(b64, validate=True)
img = Image.open(io.BytesIO(raw))
img.load()
if img.format != "PNG" or img.size != (1024, 1024):
raise ValueError(f"unexpected image: {img.format} {img.size}")
with open(path, "wb") as f:
f.write(raw)
return path
def save_asset(path, parent_asset_id=None):
asset_id = str(uuid.uuid4())
assets[asset_id] = {"path": path, "parent_asset_id": parent_asset_id}
return asset_id
# 1라운드: JSON으로 텍스트-이미지 변환
gen_resp = requests.post(
f"{BASE_URL}/images/generations",
headers=HEADERS,
json={
"model": MODEL,
"prompt": (
"Light gray background, a blue ceramic mug centered, "
"handle facing right, soft side lighting, no text."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
timeout=TIMEOUT,
)
v1_id = save_asset(decode_and_check(gen_resp, "v1.png"))
# 2라운드: 명시적으로 선택한 원본을 멀티파트로 편집
selected_id = v1_id # 사용자의 대상 버전이 불분명하면 먼저 물어보세요
with open(assets[selected_id]["path"], "rb") as f:
edit_resp = requests.post(
f"{BASE_URL}/images/edits",
headers=HEADERS, # Content-Type 수동 지정 금지; requests가 boundary를 설정
data={
"model": MODEL,
"prompt": (
"Change only the mug body to brick red. Keep the mug shape, "
"handle, composition, lighting and background unchanged."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
files={"image[]": ("v1.png", f, "image/png")},
timeout=TIMEOUT,
)
v2_id = save_asset(decode_and_check(edit_resp, "v2.png"), parent_asset_id=selected_id)
print(assets)
예시 속 timeout=(10, 360)은 문서상의 중간 설정일 뿐이고, 실제 값은 네트워크 환경과 화질 설정에 맞춰 정해야 해요. 예시에서 자동 재시도를 일부러 넣지 않은 이유는 3.2절에서 설명해요.
🚀 빠른 검증:
APIYI_KEY를 APIYI apiyi.com 콘솔에서 만든 토큰으로 설정하면 위 스크립트로 두 라운드 흐름을 끝까지 실행할 수 있어요. 신규 사용자는 먼저 무료 테스트 크레딧으로 라우팅과 파싱 로직을 확인한 뒤 프로덕션 트래픽으로 전환하면 돼요.

3 GPT Image API 마이그레이션 후 검수와 정산 방법
3.1 GPT Image API 이미지 검수의 네 가지 관문
네 가지 관문을 모두 통과해야만 앱에서 이미지를 “사용 가능”으로 표시할 수 있어요:
- HTTP 성공:
raise_for_status()가 예외를 던지지 않았어요. - 디코딩 가능: 엄격한 base64 디코딩에 성공하고 Pillow
load()도 성공했어요. - 규격 정확: 형식과 크기가 요청과 일치해요. 이 예시는 PNG, 1024×1024예요.
- 시각적 변경이 실제로 발생: v2의 컵 몸통이 실제로 벽돌색으로 바뀌었고, 컵 형태와 손잡이, 구도, 배경은 대체로 유지됐어요.
4번째 관문은 사람이 직접 확인하거나 별도 검수 단계가 필요해요. HTTP 상태 코드만으로는 모델이 제대로 바꿨는지 알 수 없거든요. 앞의 세 관문만 통과한 이미지는 기껏해야 “기술적으로 유효”할 뿐, 아직 납품할 수는 없어요. 응답에 이미지가 아예 없다면 먼저 응답 내용을 확인한 뒤 재시도 여부를 결정해야 해요. 이 문제는 도움말 센터에 별도 문서가 있으니 여기서는 반복하지 않을게요.
3.2 GPT Image API 기존 도구 비용과 검수 이미지 1장당 비용
마이그레이션 전후로 과금 기준이 달라요:
| 항목 | 기존 Responses image_generation 경로 | 독립 Images API |
|---|---|---|
| 추가 비용 | 약 $0.20의 APIYI 이미지 도구 추가 호출 비용 | 이 도구 비용 없음 |
| 해당 숫자의 의미 | 이 추가 도구 비용만 뜻하며, 전체 주문 가격도 아니고 OpenAI의 일반 가격도 아니에요 | 사용량 기반 과금 |
| 적합한 비교 방식 | “검수 이미지 1장당 비용”으로 비교 | “검수 이미지 1장당 비용”으로 비교 |
단가만으로 비교하지 말고, 아래 공식으로 통일해 비교하는 걸 권장해요:
검수 이미지 1장당 비용 = 관련 실제 과금(필요한 텍스트 호출, 이미 과금된 실패 요청과 재시도 포함) ÷ 검수를 통과한 이미지 수
분자에는 의도 판단을 위한 대화 호출, 이미 과금된 실패 요청과 재시도 등 관련 과금을 모두 포함해야 해요. 분모에는 3.1절의 네 가지 관문을 통과한 이미지만 넣어요. 통과한 이미지가 한 장도 없다면 장당 비용을 계산하지 마세요. 이때의 결론은 “단가가 높다”가 아니라 “프로세스에 문제가 있다”여야 하니까요. 마이그레이션으로 얼마나 절감되는지는 재시도율과 검수 통과율에 달려 있어요. 이 글에서는 구체적인 비율을 제시하지 않을게요.
정산 대조 데이터는 콘솔 사용 로그에서 가져오며, 그중 사용 기록의 type=2를 봐요. quota 필드를 읽는다면 플랫폼 문서에 따라 quota ÷ 500000으로 금액을 환산해요.
연결 끊김 처리는 특히 주의해야 해요. 독립 이미지 엔드포인트는 동기 방식으로 반환되는데, 연결이 중간에 끊기면 이번 요청이 이미 과금됐을 수 있고 request ID로도 이미지를 다시 찾을 수 없어요. 올바른 순서는 먼저 APIYI apiyi.com 콘솔의 사용 로그에서 이번 요청이 과금됐는지 확인한 뒤, 재전송 여부를 결정하는 거예요. 예제 코드에 자동 재시도를 넣지 않은 이유도 이 때문이에요. 자동 재시도는 연결 끊김 시 중복 과금을 일으키기 쉬워요. 속도 제한을 만났거나 채널 전환이 필요하면 도움말 센터의 채널 선택 및 429 다운그레이드 관련 문서를 참고하세요.
마이그레이션 완료의 검증 기준은 아주 명확해요. 텍스트 대화는 평소처럼 사용 가능하고, 첫 이미지 생성이 네 가지 관문을 통과하는 v1을 안정적으로 반환하며, 이미지를 수정할 때마다 자산 기록에서 명확한 parent_asset_id를 확인할 수 있고, 콘솔 로그의 모든 이미지 과금이 검수 이미지 한 장, 알려진 실패 한 건, 또는 기록이 남은 재전송 한 건에 대응돼야 해요. 이 항목들이 모두 충족되면 나머지 Responses 이미지 생성 트래픽을 Images API로 전환할 수 있어요. 여러 모델을 비교 테스트해야 할 때 APIYI apiyi.com은 통합 OpenAI 호환 인터페이스를 제공하므로, 모델을 바꿀 때 MODEL 파라미터 하나만 수정하면 돼요.
참고 자료
-
APIYI 문서 업데이트: 공식 중계 이미지 모델이 Images API로 전환
- 링크:
docs.apiyi.com/live/2026-11/gpt-image-official-relay-images-api - 설명: 5종의 공식 중계 ID, 2개의 독립 엔드포인트, 그리고 기존 경로를 권장하지 않는 이유
- 링크:
-
APIYI FAQ: 하나의 API에서 텍스트와 이미지를 동시에 처리하기
- 링크:
docs.apiyi.com/faq/text-and-image-in-one-api - 설명: 대화 모델이 의도를 판단하고, 애플리케이션이 Images API를 별도로 호출하는 조합 방식
- 링크:
-
OpenAI 이미지 생성 가이드
- 링크:
developers.openai.com/api/docs/guides/image-generation - 설명: Responses의 연속 편집 방식과 응답 구조
- 링크:
-
APIYI GPT Image 2 텍스트-이미지 변환 / 이미지 편집
- 링크:
docs.apiyi.com/api-capabilities/gpt-image-2/text-to-image - 링크:
docs.apiyi.com/api-capabilities/gpt-image-2/image-edit - 설명: 요청 파라미터, multipart 업로드와 디코딩 검증 예시
- 링크:
-
APIYI Responses 이미지 도구 / 이미지 API 모범 사례 / 로그 조회
- 링크:
docs.apiyi.com/api-capabilities/gpt-image-2/responses-image-tool - 링크:
docs.apiyi.com/api-capabilities/image-api-best-practices - 링크:
docs.apiyi.com/api-capabilities/log-query - 설명: 도구 요금 기준, 연결 끊김 처리, 사용 로그 환산
- 링크:
작성자: APIYI 기술팀
기술 문의: 마이그레이션 중 라우팅이나 청구 문제가 발생하면 APIYI apiyi.com 홈페이지를 통해 연락 주세요. 더 자세한 인터페이스 내용은 docs.apiyi.com 문서 센터에서 확인하실 수 있습니다.
