Google GenAI 이미지 생성

Google GenAI 이미지 생성 (Google GenAI Image)

Gemini 2.5 Flash Image Model과 Gemini 3.1 Flash Image Model은 Gemini Developer API 또는 Vertex AI를 통해 Google의 이미지 모델을 사용한 이미지 생성을 제공해요. 주류 가격과 낮은 지연 시간으로 고품질 이미지 생성과 대화형 편집을 제공하죠. 이 글에서는 인증 모드, 프로퍼티 설정, 안전 필터 수준, 인물 생성 옵션까지 알아볼게요.

출처: 문서

본문

Gemini 2.5 Flash Image Model과 Gemini 3.1 Flash Image Model은 Gemini Developer API 또는 Vertex AI를 통해 Google의 이미지 모델을 사용한 이미지 생성을 제공해요.

주류 가격대와 낮은 지연 시간으로 고품질 이미지 생성과 대화형 편집을 제공해요.

속도와 대규모 개발자 사용 사례에 최적화된 Gemini 3 Pro Image Model의 고효율 대응 모델로 사용돼요.

이 구현은 두 가지 인증 모드를 제공해요:

Gemini Developer API : 빠른 프로토타이핑과 개발을 위해 API 키 사용
Vertex AI : 엔터프라이즈 기능과 함께 프로덕션 배포를 위해 Google Cloud 자격 증명 사용

Prerequisites

다음 인증 방법 중 하나를 선택하세요:

Option 1: Gemini Developer API (API Key)

Google AI Studio에서 API 키를 얻으세요
API 키를 환경 변수나 애플리케이션 프로퍼티로 설정하세요

Option 2: Vertex AI (Google Cloud)

운영체제에 맞는 gcloud CLI를 설치하세요.
다음 명령을 실행해 인증하세요. PROJECT_ID를 Google Cloud 프로젝트 ID로, ACCOUNT를 Google Cloud 사용자 이름으로 바꾸세요.

gcloud config set project <PROJECT_ID> && gcloud auth application-default login

Add Repositories and BOM

Spring AI 아티팩트는 Maven Central과 Spring Snapshot 저장소에 게시돼요. 빌드 시스템에 이러한 저장소를 추가하려면 Artifact Repositories 섹션을 참고하세요.

의존성 관리를 돕기 위해 Spring AI는 프로젝트 전체에서 일관된 Spring AI 버전을 사용하도록 보장하는 BOM(bill of materials)을 제공해요. 빌드 시스템에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고하세요.

Auto-configuration

__	Spring AI 자동 설정과 스타터 모듈 아티팩트 이름에 큰 변경이 있었어요. 자세한 내용은 upgrade notes를 참고해주세요.

Spring AI는 Google GenAI 이미지 모델에 대한 Spring Boot 자동 설정을 제공해요. 활성화하려면 프로젝트의 Maven pom.xml 파일에 다음 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai-image</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 추가할 수도 있어요:

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai-image'
}

__	빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

Image generation Properties

Connection Properties

프리픽스 spring.ai.google.genai.image는 Google GenAI 이미지 생성 API에 연결할 수 있게 해주는 프로퍼티 프리픽스예요.

__	연결 프로퍼티는 Google GenAI Chat 모듈과 공유돼요. chat과 image를 모두 사용한다면 `spring.ai.google.genai` 프리픽스(chat용) 또는 `spring.ai.google.genai.image` 프리픽스(images용) 중 하나로 연결을 한 번만 구성하면 돼요.

Property	Description	Default
spring.ai.google.genai.image.api-key	Gemini Developer API용 API 키. 제공되면 클라이언트는 Vertex AI 대신 Gemini Developer API를 사용해요.	-
spring.ai.google.genai.image.project-id	Google Cloud Platform 프로젝트 ID (Vertex AI 모드에 필요)	-
spring.ai.google.genai.image.location	Google Cloud 리전 (Vertex AI 모드에 필요)	-
spring.ai.google.genai.image.credentials-uri	Google Cloud 자격 증명 URI. 제공되면 인증을 위한 `GoogleCredentials` 인스턴스를 만드는 데 사용돼요.	-

__ 자동 설정의 활성화/비활성화는 이제 프리픽스 spring.ai.model.image이 붙은 최상위 프로퍼티로 설정해요. 활성화하려면 spring.ai.model.image=google-genai (기본값으로 활성화됨). 비활성화하려면 spring.ai.model.image=none (또는 google-genai와 일치하지 않는 어떤 값). 이 변경은 여러 모델의 설정을 허용하기 위한 것이에요.

Image generation Properties

프리픽스 spring.ai.google.genai.image는 Google GenAI의 이미지 모델 구현을 구성할 수 있게 해주는 프로퍼티 프리픽스예요.

Property	Description	Default
spring.ai.model.image	Google GenAI API 모델 활성화.	google-genai
spring.ai.google.genai.image.n	생성할 이미지 수. 1에서 4 사이여야 해요.	-
spring.ai.google.genai.image.model	사용할 Google GenAI 모델. 지원 모델에는 `gemini-2.5-flash-image`, `gemini-3-pro-image`, `gemini-3.1-flash-image`가 있어요	-
spring.ai.google.genai.image.aspect-ratio	생성된 이미지의 종횡비. 지원 값은 1:1, 3:4, 4:3, 9:16, 16:9	1:1
spring.ai.google.genai.image.seed	이미지 생성을 위한 랜덤 시드. `add-watermark`가 true로 설정되면 사용할 수 없어요.	-
spring.ai.google.genai.image.safety-filter-level	안전 필터링 수준. 지원 값은 BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH, BLOCK_NONE	-
spring.ai.google.genai.image.person-generation	모델이 사람을 생성하도록 허용. 지원 값은 DONT_ALLOW, ALLOW_ADULT, ALLOW_ALL	-
spring.ai.google.genai.image.output-mime-type	생성된 이미지의 MIME 타입.	-
spring.ai.google.genai.image.output-compression-quality	생성된 이미지의 압축 품질 (`image/jpeg`에만 해당).	-
spring.ai.google.genai.image.labels	청구 사용량 추적을 위한 사용자 지정 레이블.	-
spring.ai.google.genai.image.image-size	생성된 이미지의 가장 큰 차원의 크기. 지원 크기는 1K와 2K.	-
spring.ai.google.genai.image.temperature	토큰 선택의 무작위성 정도를 제어해요. 낮은 값은 덜 개방적인 응답을, 높은 값은 더 다양하거나 창의적인 결과를 생성해요.	-
spring.ai.google.genai.image.top-p	토큰을 가장 높은 확률부터 가장 낮은 확률까지 선택하되, 해당 확률의 합이 이 값과 같아질 때까지 선택해요.	-
spring.ai.google.genai.image.top-k	각 토큰 선택 단계에서, 가장 높은 확률을 가진 `top-k` 토큰이 샘플링돼요.	-
spring.ai.google.genai.image.max-output-tokens	응답에서 생성할 수 있는 최대 토큰 수.	-

Sample Controller

새 Spring Boot 프로젝트를 만들고, pom(또는 gradle) 의존성에 spring-ai-starter-model-google-genai-image을 추가하세요.

src/main/resources 디렉터리 아래에 application.properties 파일을 추가해 Google GenAI 이미지 모델을 활성화하고 구성해요:

Using Gemini Developer API (API Key)

spring.ai.google.genai.image.api-key=YOUR_API_KEY
spring.ai.google.genai.image.model=gemini-2.5-flash-image

Using Vertex AI

spring.ai.google.genai.image.project-id=YOUR_PROJECT_ID
spring.ai.google.genai.image.location=YOUR_PROJECT_LOCATION
spring.ai.google.genai.image.model=gemini-2.5-flash-image

이렇게 하면 클래스에 주입할 수 있는 GoogleGenAiImageModel 구현이 생성돼요. 이미지 생성을 위해 이미지 모델을 사용하는 간단한 @Controller 클래스 예시예요:

@RestController
public class ImageController {

    private final ImageModel imageModel;

    @Autowired
    public ImageController(ImageModel imageModel) {
        this.imageModel = imageModel;
    }

    @GetMapping("/ai/image")
    public Map generate(@RequestParam(value = "message", defaultValue = "A painting of a sunset over a mountain") String message) {
        ImagePrompt imagePrompt = new ImagePrompt(message);
        ImageResponse imageResponse = this.imageModel.call(imagePrompt);
        return Map.of("images", imageResponse);
    }
}

Manual Configuration

GoogleGenAiImageModel은 ImageModel을 구현해요.

프로젝트의 Maven pom.xml 파일에 spring-ai-google-genai-image 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-google-genai-image</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 추가할 수도 있어요:

dependencies {
    implementation 'org.springframework.ai:spring-ai-google-genai-image'
}

__	빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

다음으로 GoogleGenAiImageModel을 만들고 이미지에 사용해요:

Using API Key

GoogleGenAiImageConnectionDetails connectionDetails =
    GoogleGenAiImageConnectionDetails.builder()
        .apiKey(System.getenv("GOOGLE_API_KEY"))
        .build();

GoogleGenAiImageOptions options = GoogleGenAiImageOptions.builder()
    .model(GoogleGenAiImageOptions.DEFAULT_MODEL_NAME)
    .build();

var imageModel = new GoogleGenAiImageModel(connectionDetails, options);

ImageResponse imageResponse = imageModel
	.call(new ImagePrompt("A painting of a sunset over a mountain"));

Using Vertex AI

GoogleGenAiImageConnectionDetails connectionDetails =
    GoogleGenAiImageConnectionDetails.builder()
        .projectId(System.getenv("GOOGLE_CLOUD_PROJECT"))
        .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
        .build();

GoogleGenAiImageOptions options = GoogleGenAiImageOptions.builder()
    .model(GoogleGenAiImageOptions.DEFAULT_MODEL_NAME)
    .build();

var imageModel = new GoogleGenAiImageModel(connectionDetails, options);

ImageResponse imageResponse = imageModel
	.call(new ImagePrompt("A painting of a sunset over a mountain"));

Safety Filter Levels

Google GenAI 이미지 API는 안전 필터링을 위한 다양한 필터 수준을 지원해요:

BLOCK_LOW_AND_ABOVE: 안전하지 않은 콘텐츠의 낮음(low), 중간(medium), 높음(high) 확률에서 차단
BLOCK_MEDIUM_AND_ABOVE: 안전하지 않은 콘텐츠의 중간(medium) 또는 높음(high) 확률에서 차단
BLOCK_ONLY_HIGH: 안전하지 않은 콘텐츠의 높음(high) 확률에서 차단
BLOCK_NONE: 안전하지 않은 콘텐츠의 확률과 무관하게 항상 표시
SAFETY_FILTER_LEVEL_UNSPECIFIED: 임계값이 지정되지 않음, 기본 임계값으로 차단

Person Generation

Google GenAI 이미지 API는 서로 다른 수준으로 사람의 이미지를 생성하도록 모델을 허용해요:

DONT_ALLOW: 사람 이미지 생성 차단
ALLOW_ADULT: 성인의 이미지는 생성하되, 어린이는 생성하지 않음
ALLOW_ALL: 성인과 어린이를 모두 포함한 이미지 생성
PERSON_GENERATION_UNSPECIFIED: 임계값이 지정되지 않음, 기본 임계값으로 사람 이미지 생성

Google GenAI 이미지 생성