> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 만족스러운 이미지를 얻는 방법

> 웹 앱과 API의 근본적인 차이를 설명하는 실제 이미지 편집 사례 연구로, 단일 호출 변동성이 어디에서 비롯되는지와 더 나은 prompt, 재시도, 모델 전환, 테스트 도구로 문제를 분리하는 네 가지 실용적인 전략을 다룹니다.

첫 시도에서 만족스럽지 못한 이미지를 받는 것은 정상입니다 — **만족스럽지 못함 ≠ 나쁜 모델, 그리고 확실히 ≠ 나쁜 게이트웨이**. 이 페이지에서는 실제 고객 사례를 통해 같은 모델이 웹 앱과 API에서 왜 다르게 동작하는지, 실제 변동성이 어디에서 비롯되는지, 그리고 성공률을 눈에 띄게 높이는 네 가지 전략을 설명합니다.

## 사례 연구: 색상을 잘못 맞춘 편집

작업 내용: 장난감 차 세트의 제품 시트로, 왼쪽 아래의 두 "Cups" 중 하나는 회색이고 하나는 초록색이며, 빨간 상자로 표시되어 있습니다. 프롬프트:

> 빨간 상자 안의 항목을 검은색으로 바꾸고, 빨간 상자를 제거하며, 나머지는 모두 그대로 유지하십시오

<Frame caption="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">
  <img src="https://mintcdn.com/apiyillc/YlApNMokaLGR-mkl/images/image-edit-case-teaset-original.jpg?fit=max&auto=format&n=YlApNMokaLGR-mkl&q=85&s=f5b3a4848c8d8256c574ffa72a0fc88a" alt="왼쪽 아래에 빨간 상자로 표시된 두 컵이 있는 장난감 차 세트 제품 시트" width="1024" height="1021" data-path="images/image-edit-case-teaset-original.jpg" />
</Frame>

고객은 `gemini-3.1-flash-image` (Nano Banana 2)를 API를 통해 호출했고, 다음 결과를 받았습니다:

<Frame caption="Failed result from a single API call: both cups turned green, and the red box was not removed">
  <img src="https://mintcdn.com/apiyillc/LihN1TRFUvEsZ0oh/images/image-edit-case-teaset-api-result.jpg?fit=max&auto=format&n=LihN1TRFUvEsZ0oh&q=85&s=ba1ec09f532b9266ad0e6012384a98d0" alt="편집 실패 결과: 빨간 상자 안의 두 컵이 요청한 검은색이 아니라 초록색으로 바뀌었고, 빨간 상자도 여전히 남아 있습니다" width="1024" height="1024" data-path="images/image-edit-case-teaset-api-result.jpg" />
</Frame>

**색상이 잘못 나왔습니다** — 검은색이 요청되었지만, 결과에는 빨간 상자가 그대로 있는 두 개의 초록색 컵이 표시됩니다. 한편, 고객은 같은 모델로 같은 편집을 Gemini 웹 앱(`gemini.google.com`)에서 실행했는데 잘 작동했습니다. 고객의 피드백은 다음과 같습니다:

> API 출력이 공식(웹) 출력과 완전히 다릅니다 — 마치 API가 그만큼 잘 이해하지 못하는 것처럼 느껴집니다.

불만은 충분히 이해되지만, 원인 설명은 바로잡아야 합니다. 이를 하나씩 살펴보겠습니다.

## 먼저 이해하셔야 합니다: 웹 앱은 에이전트이고, API는 단일 원자적 호출입니다

`gemini.google.com` 결과를 원시 API 호출과 직접 비교하는 것은 같은 기준의 비교가 아닙니다:

|            | Gemini 웹 앱                                    | 직접 API 호출                    |
| ---------- | --------------------------------------------- | ---------------------------- |
| 제품 형태      | **완전한 에이전트**                                  | **단일 원자적 호출**                |
| 사용자 prompt | 모델에 도달하기 전에 시스템에 의해 **다시 작성, 확장, 개선**될 수 있습니다 | **그대로** 모델에 도달합니다            |
| 실행         | 여러 단계의 오케스트레이션, 내부 재시도/선택이 있을 수 있습니다          | 한 번의 샘플링 패스로, 직접 반환됩니다       |
| 기반 모델      | gemini-3.1-flash-image                        | gemini-3.1-flash-image (동일함) |

같은 모델, 두 가지 제품 형태입니다. 웹 앱은 여러분의 일상적인 지시를 모델이 더 안정적으로 실행하는 형태로 다듬어 줍니다. 반면 API에서는 **그 다듬는 작업이 여러분의 몫**입니다(그리고 바로 그것이 API의 정확한 가치입니다: 모든 것이 제어 가능하고, 재현 가능하며, 통합 가능합니다).

<Info>
  따라서 "웹 앱이 더 잘 작동한다"는 것은 대부분 **파이프라인 차이**에서 비롯된 것이며, "API가 덜 이해한다"는 결론을 뒷받침하지는 않습니다. API는 가공되지 않은 원시 prompt를 그대로 받기 때문에, 결과는 자연스럽게 prompt 자체의 품질에 더 크게 좌우됩니다.
</Info>

## 단일 호출 편차는 생성형 모델의 본질적 특성입니다

우리는 [imagen.apiyi.com](https://imagen.apiyi.com) 테스트 도구에서 **완전히 동일한 prompt + 이미지**로 작업을 다시 시도했습니다: **첫 시도에 성공했습니다** — 컵은 검은색으로 바뀌고, 빨간 상자는 제거되었으며, 나머지는 모두 그대로였습니다.

<Info>
  명확히 말씀드리면, imagen.apiyi.com과 raw API 호출의 유일한 차이는 내장된 “이미지를 생성” 의도 prompt입니다. 이는 모델이 이미지 출력을 확정하도록 돕지만, 이 사례의 정교한 편집이 성공하느냐와는 아무 관련이 없습니다 — **도구가 “비법”을 더했기 때문에 성공한 것은 아닙니다**.
</Info>

같은 입력, 같은 모델, 같은 게이트웨이 — 한 번은 실패하고 한 번은 성공했습니다. 이것이 무엇을 말해줍니까?

**생성형 모델의 개별 출력은 본질적으로 확률적입니다.** 모든 호출은 독립적인 샘플링 과정이며, 복합 지시(박스로 위치를 찾기 + 색상 변경 + 박스 제거 + 나머지 모두 보존)는 개별 샘플에서 가끔 빗나가기 쉬운 유형입니다. 이는 게이트웨이 문제도 아니고, API가 “단순화된” 것도 아닙니다 — 모델 고유의 편차입니다.

편차의 원천을 이해하면 전략은 분명해집니다 — 비용 대비 효과 순으로 네 가지를 소개합니다.

## 전략 1: 프롬프트 개선하기

프롬프트가 덜 모호하고 더 실행 가능할수록 단일 호출 성공률은 높아집니다. 이 사례를 예로 들면:

**원본 프롬프트** (캐주얼하고, 모델이 추론하길 기대함):

> 빨간 상자 안의 항목을 검정색으로 바꾸고, 빨간 상자를 제거하고, 나머지는 모두 그대로 유지하세요

**개선 방법**:

| 기법                     | 원문               | 개선본                                                  |
| ---------------------- | ---------------- | ---------------------------------------------------- |
| 지시 대상 대신 구체적인 명사를 사용하기 | "빨간 상자 안의 항목"    | "빨간 상자 안의 **두 잔**"                                   |
| 색상을 구체적으로 설명하기         | "검정색으로 바꾸기"      | "원래의 재질 질감을 보존한 채 **무광 순수 검정**으로 바꾸기"                |
| 유지해야 할 항목을 열거하기        | "나머지는 모두 그대로 유지" | "이미지의 **다른 모든 항목**의 색상, 위치, 텍스트 레이블을 그대로 유지하기"       |
| 작업 순서를 명시적으로 번호 매기기    | 한 문장에 섞어 넣음      | "두 가지를 수행하세요: ① 두 잔을 검정색으로 재색칠하기; ② 빨간 상자 윤곽선을 삭제하기" |

**개선된 전체 프롬프트 예시**:

> 이 이미지를 편집하여 두 가지를 수행하세요: ① 빨간 상자 안의 두 잔을 무광 순수 검정으로 바꾸되, 원래의 재질 질감과 형태는 보존하세요; ② 빨간 상자 윤곽선 자체를 삭제하세요. 이미지의 다른 모든 항목의 색상, 위치, 치수 레이블, 텍스트는 완전히 그대로 유지하세요.

<Tip>
  일반 원칙: **한 번에 한 종류의 것만 바꾸세요**. 편집에 여러 작업(재색칠 + 배경 교체 + 텍스트 추가 등)이 포함된다면 여러 번의 편집 단계로 나누세요. 각 단계의 성공률은 하나의 복합 지시보다 훨씬 높아집니다.
</Tip>

### 어떻게 개선해야 할지 모르겠다면? AI에게 다시 쓰게 하세요

프롬프트를 개선하는 일 자체도 AI에 맡길 수 있습니다. 널리 알려지고 신뢰할 수 있는 AI 채팅 제품(예: `chatgpt.com` 또는 `gemini.google.com`)에 다음 세 가지를 함께 보내면 됩니다:

1. **원본 프롬프트** (그대로 붙여넣기);
2. **문제 설명** (예: "검정색을 요청했는데 초록색이 나왔고, 빨간 상자도 제거되지 않았습니다");
3. **전후 비교** (원본 이미지와 실제 출력 결과를 함께 업로드).

그다음 "이 실패 결과를 바탕으로, 더 정확하고 모호성이 적은 이미지 편집 프롬프트로 다시 작성해 주세요"라고 요청하세요. 보통 한 번만으로도 눈에 띄게 더 나은 버전을 얻을 수 있습니다.

그 사이트에 접속할 수 없다면, APIYI도 AI 채팅 수요를 충분히 충족합니다. 우리 API를 **Cherry Studio** 또는 **Chatbox** 같은 채팅 클라이언트에 연결해 보세요. 문서의 "Scenarios - Chat" 아래 튜토리얼을 참고하시면 됩니다:

* [Cherry Studio 설정 튜토리얼](/ko/scenarios/chat/cherry-studio)
* [Chatbox 설정 튜토리얼](/ko/scenarios/chat/chatbox)

## 전략 2: 실패 시 재시도

실패는 단일 샘플 변동성에서 비롯되므로, **재시도 자체가 효과적인 해결책입니다** — 동일한 요청을 다시 보내면 대개 그대로 작동합니다(이번 사례에서도 정확히 그렇게 되었습니다).

* 비즈니스 코드에서는 “결과가 기대와 일치하지 않음”에 대해 자동 재시도를 1–2회 정도 두십시오;
* 두 가지 실패 유형을 구분하십시오: “이미지는 반환되었지만 편집이 잘못됨”과 “이미지가 전혀 없음”입니다. 후자(HTTP 200이지만 이미지 없음)는 보통 콘텐츠 모더레이션 차단입니다 — [Gemini Image API 오류 처리 가이드](/ko/api-capabilities/gemini-image-error-handling)를 참조하십시오.

## 전략 3: 모델 전환

이 사례에서는 동일한 prompt + image로 다른 모델들을 테스트했으며 — **모두 첫 시도에 성공했습니다**:

| 모델                                     | 결과        |
| -------------------------------------- | --------- |
| `gemini-3-pro-image` (Nano Banana Pro) | ✅ 첫 시도 성공 |
| `gemini-3.1-flash-lite-image`          | ✅ 첫 시도 성공 |
| `gpt-image-2` 시리즈                      | ✅ 첫 시도 성공 |

모델마다 잘하는 지시 유형이 다릅니다. 어떤 모델에서는 계속 실패하는 작업이 다른 모델에서는 즉시 통과할 수 있습니다. APIYI 통합 게이트웨이에서는 모델을 전환할 때 `model` 파라미터만 바꾸면 됩니다(같은 키, 같은 endpoint) — 비용은 거의 0에 가깝습니다. **이미지 워크플로에서 "모델 전환"을 1급 단계로 두십시오. 이는 목표에 도달하기 위한 정당한 전략이지, 타협이 아닙니다.**

실무에서는 "빠른 모델 우선, 강한 모델은 나중" 사다리로 구성하십시오:

1. 일상적인 작업에는 빠르고 저렴한 모델(예: `gemini-3.1-flash-image`)을 기본으로 사용하십시오.
2. 정밀 편집 작업이 1\~2회 실패하면 자동으로 `gemini-3-pro-image` 또는 `gpt-image-2` 시리즈로 승격해 다시 시도하십시오.
3. 아무것도 통하지 않으면, 다시 돌아가 prompt를 재작성하십시오.

## 전략 4: 테스트 도구로 먼저 문제를 분리하기

“출력이 왜 잘못되는지”를 디버깅할 때는 먼저 변수를 분리합니다. [imagen.apiyi.com](https://imagen.apiyi.com)에서는 코드를 작성하지 않고도 “prompt + image” 조합을 빠르게 검증할 수 있습니다.

* **도구에서도 실패함** → 대부분 prompt/작업 문제입니다. 전략 1로 돌아가거나, 전략 3에 따라 모델을 바꾸십시오;
* **도구에서는 성공하지만 코드에서는 실패함** → 코드를 점검하십시오. 이미지가 완전히 업로드되었는지, 파라미터가 올바른지, prompt가 잘리거나 이스케이프 처리로 인해 망가졌는지 확인하십시오;
* **때로는 되고 때로는 실패함** → 샘플링 분산입니다. 전략 2에 따라 재시도를 추가하십시오.

이렇게 하면 prompt 문제를 gateway 문제로 오진하는 일을 막을 수 있고, 불필요한 우회도 많이 줄일 수 있습니다.

## 빠른 참고

* **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 문제, 코드 문제, 샘플링 변동성을 구분하십시오.

## 관련 문서

* [Gemini Image API 오류 처리 가이드](/ko/api-capabilities/gemini-image-error-handling)
* [이미지 압축 및 출력 해상도](/ko/api-capabilities/image-compression-resolution)
* [Nano Banana 시리즈 개발자 가이드](/ko/api-capabilities/nano-banana-dev-guide)