사례 연구: 색상을 잘못 맞춘 편집
작업 내용: 장난감 차 세트의 제품 시트로, 왼쪽 아래의 두 “Cups” 중 하나는 회색이고 하나는 초록색이며, 빨간 상자로 표시되어 있습니다. 프롬프트:빨간 상자 안의 항목을 검은색으로 바꾸고, 빨간 상자를 제거하며, 나머지는 모두 그대로 유지하십시오
Input image: a red box marks the two cups (one gray, one green) in the lower left; the request is to make them black and remove the box
gemini-3.1-flash-image (Nano Banana 2)를 API를 통해 호출했고, 다음 결과를 받았습니다:
Failed result from a single API call: both cups turned green, and the red box was not removed
gemini.google.com)에서 실행했는데 잘 작동했습니다. 고객의 피드백은 다음과 같습니다:
API 출력이 공식(웹) 출력과 완전히 다릅니다 — 마치 API가 그만큼 잘 이해하지 못하는 것처럼 느껴집니다.불만은 충분히 이해되지만, 원인 설명은 바로잡아야 합니다. 이를 하나씩 살펴보겠습니다.
먼저 이해하셔야 합니다: 웹 앱은 에이전트이고, API는 단일 원자적 호출입니다
gemini.google.com 결과를 원시 API 호출과 직접 비교하는 것은 같은 기준의 비교가 아닙니다:
같은 모델, 두 가지 제품 형태입니다. 웹 앱은 여러분의 일상적인 지시를 모델이 더 안정적으로 실행하는 형태로 다듬어 줍니다. 반면 API에서는 그 다듬는 작업이 여러분의 몫입니다(그리고 바로 그것이 API의 정확한 가치입니다: 모든 것이 제어 가능하고, 재현 가능하며, 통합 가능합니다).
따라서 “웹 앱이 더 잘 작동한다”는 것은 대부분 파이프라인 차이에서 비롯된 것이며, “API가 덜 이해한다”는 결론을 뒷받침하지는 않습니다. API는 가공되지 않은 원시 prompt를 그대로 받기 때문에, 결과는 자연스럽게 prompt 자체의 품질에 더 크게 좌우됩니다.
단일 호출 편차는 생성형 모델의 본질적 특성입니다
우리는 imagen.apiyi.com 테스트 도구에서 완전히 동일한 prompt + 이미지로 작업을 다시 시도했습니다: 첫 시도에 성공했습니다 — 컵은 검은색으로 바뀌고, 빨간 상자는 제거되었으며, 나머지는 모두 그대로였습니다.명확히 말씀드리면, imagen.apiyi.com과 raw API 호출의 유일한 차이는 내장된 “이미지를 생성” 의도 prompt입니다. 이는 모델이 이미지 출력을 확정하도록 돕지만, 이 사례의 정교한 편집이 성공하느냐와는 아무 관련이 없습니다 — 도구가 “비법”을 더했기 때문에 성공한 것은 아닙니다.
전략 1: 프롬프트 개선하기
프롬프트가 덜 모호하고 더 실행 가능할수록 단일 호출 성공률은 높아집니다. 이 사례를 예로 들면: 원본 프롬프트 (캐주얼하고, 모델이 추론하길 기대함):빨간 상자 안의 항목을 검정색으로 바꾸고, 빨간 상자를 제거하고, 나머지는 모두 그대로 유지하세요개선 방법:
개선된 전체 프롬프트 예시:
이 이미지를 편집하여 두 가지를 수행하세요: ① 빨간 상자 안의 두 잔을 무광 순수 검정으로 바꾸되, 원래의 재질 질감과 형태는 보존하세요; ② 빨간 상자 윤곽선 자체를 삭제하세요. 이미지의 다른 모든 항목의 색상, 위치, 치수 레이블, 텍스트는 완전히 그대로 유지하세요.
어떻게 개선해야 할지 모르겠다면? AI에게 다시 쓰게 하세요
프롬프트를 개선하는 일 자체도 AI에 맡길 수 있습니다. 널리 알려지고 신뢰할 수 있는 AI 채팅 제품(예:chatgpt.com 또는 gemini.google.com)에 다음 세 가지를 함께 보내면 됩니다:
- 원본 프롬프트 (그대로 붙여넣기);
- 문제 설명 (예: “검정색을 요청했는데 초록색이 나왔고, 빨간 상자도 제거되지 않았습니다”);
- 전후 비교 (원본 이미지와 실제 출력 결과를 함께 업로드).
전략 2: 실패 시 재시도
실패는 단일 샘플 변동성에서 비롯되므로, 재시도 자체가 효과적인 해결책입니다 — 동일한 요청을 다시 보내면 대개 그대로 작동합니다(이번 사례에서도 정확히 그렇게 되었습니다).- 비즈니스 코드에서는 “결과가 기대와 일치하지 않음”에 대해 자동 재시도를 1–2회 정도 두십시오;
- 두 가지 실패 유형을 구분하십시오: “이미지는 반환되었지만 편집이 잘못됨”과 “이미지가 전혀 없음”입니다. 후자(HTTP 200이지만 이미지 없음)는 보통 콘텐츠 모더레이션 차단입니다 — Gemini Image API 오류 처리 가이드를 참조하십시오.
전략 3: 모델 전환
이 사례에서는 동일한 prompt + image로 다른 모델들을 테스트했으며 — 모두 첫 시도에 성공했습니다:
모델마다 잘하는 지시 유형이 다릅니다. 어떤 모델에서는 계속 실패하는 작업이 다른 모델에서는 즉시 통과할 수 있습니다. APIYI 통합 게이트웨이에서는 모델을 전환할 때
model 파라미터만 바꾸면 됩니다(같은 키, 같은 endpoint) — 비용은 거의 0에 가깝습니다. 이미지 워크플로에서 “모델 전환”을 1급 단계로 두십시오. 이는 목표에 도달하기 위한 정당한 전략이지, 타협이 아닙니다.
실무에서는 “빠른 모델 우선, 강한 모델은 나중” 사다리로 구성하십시오:
- 일상적인 작업에는 빠르고 저렴한 모델(예:
gemini-3.1-flash-image)을 기본으로 사용하십시오. - 정밀 편집 작업이 1~2회 실패하면 자동으로
gemini-3-pro-image또는gpt-image-2시리즈로 승격해 다시 시도하십시오. - 아무것도 통하지 않으면, 다시 돌아가 prompt를 재작성하십시오.
전략 4: 테스트 도구로 먼저 문제를 분리하기
“출력이 왜 잘못되는지”를 디버깅할 때는 먼저 변수를 분리합니다. imagen.apiyi.com에서는 코드를 작성하지 않고도 “prompt + image” 조합을 빠르게 검증할 수 있습니다.- 도구에서도 실패함 → 대부분 prompt/작업 문제입니다. 전략 1로 돌아가거나, 전략 3에 따라 모델을 바꾸십시오;
- 도구에서는 성공하지만 코드에서는 실패함 → 코드를 점검하십시오. 이미지가 완전히 업로드되었는지, 파라미터가 올바른지, prompt가 잘리거나 이스케이프 처리로 인해 망가졌는지 확인하십시오;
- 때로는 되고 때로는 실패함 → 샘플링 분산입니다. 전략 2에 따라 재시도를 추가하십시오.
빠른 참고
- Web app ≠ API: 웹 앱은 prompt 재작성과 다단계 오케스트레이션을 포함하는 완전한 에이전트입니다. API는 사용자가 적은 prompt를 그대로 사용하는 단일 원자 호출입니다. 체감되는 차이는 대체로 파이프라인에서 비롯되며, “API가 덜 이해한다”는 데서 오는 것이 아닙니다.
- 무작위 단일 호출 편차는 생성형 모델에 본질적으로 내재되어 있습니다. 한 번의 실패로는 모델이나 게이트웨이에 대해 아무것도 말해주지 않습니다.
- 전략 1, prompt를 개선합니다: 구체적인 명사, 구체적인 색상, 보존할 항목을 열거하고, 작업을 번호로 나열합니다. 한 번에 한 종류의 것만 바꾸십시오.
- 전략 2, 재시도합니다: “wrong edit”에는 재시도 1~2회를 할당하십시오. “no image”는 다른 문제입니다(오류 처리 가이드를 참조하십시오).
- 전략 3, 모델을 전환합니다: 이 경우
gemini-3-pro-image,gemini-3.1-flash-lite-image, 그리고gpt-image-2시리즈가 모두 첫 시도에 성공했습니다. 통합 게이트웨이에서는 매개변수 하나만 바꾸면 됩니다. - 전략 4, 테스트 도구로 분리합니다: 먼저 imagen.apiyi.com에서 “prompt + image”를 검증하여 prompt 문제, 코드 문제, 샘플링 변동성을 구분하십시오.