Google Gemini 이미지 형식 (Image)¶

공식 문서

📝 소개¶

텍스트 프롬프트를 전달하면 모델이 새 이미지를 생성합니다. Google Gemini는 자연어 설명을 기반으로 이미지를 생성할 수 있는 강력한 모델을 제공합니다.

🤖 지원 모델¶

현재 지원되는 모델:

모델	설명
gemini-2.5-flash-image	텍스트 프롬프트 기반 고품질 이미지 생성을 지원하는 Google Gemini 이미지 생성 모델
gemini-3-pro-image-preview	텍스트 프롬프트 기반 이미지 생성과 입력 이미지+텍스트 프롬프트 기반 이미지 편집을 지원하는 Google Gemini 이미지 생성/편집 모델

💡 요청 예시¶

이미지 생성 ✅¶

# 기본 이미지 생성
curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-2.5-flash-image:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Give me an image of a cat"}]
    }]
  }'

응답 예시:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is an image for you: "
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "..."
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 1298,
    "totalTokenCount": 1307,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 9
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "IMAGE",
        "tokenCount": 1290
      }
    ]
  },
  "modelVersion": "gemini-2.5-flash-image",
  "responseId": "..."
}

이미지 편집 ✅¶

# 이미지 편집
curl "https://ssanai-workspace.atto-lab.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key=$API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        {"text": "put the chips in the given image on a beach."},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "$IMG_BASE64"
          }
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "2K"
      }
    }
  }'

응답 예시:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Here is the edited image for you: "
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "..."
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 15,
    "candidatesTokenCount": 1350,
    "totalTokenCount": 1365,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 15
      },
      {
        "modality": "IMAGE",
        "tokenCount": 1200
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "IMAGE",
        "tokenCount": 1350
      }
    ]
  },
  "modelVersion": "gemini-3-pro-image-preview",
  "responseId": "..."
}

📮 요청¶

엔드포인트¶

이미지 생성¶

POST /v1beta/models/gemini-2.5-flash-image:generateContent

텍스트 프롬프트를 기반으로 이미지를 생성합니다.

이미지 편집¶

POST /v1beta/models/gemini-3-pro-image-preview:generateContent

입력 이미지와 텍스트 프롬프트를 기반으로 이미지를 편집하거나 새로 생성합니다. gemini-2.5-flash-image 및 gemini-3-pro-image-preview 모델을 지원합니다.

인증 방법¶

요청 URL 파라미터에 API 키를 포함하세요:

?key=$API_KEY

$API_KEY는 발급받은 API 키입니다.

요청 본문 파라미터¶

`contents`¶

유형: 배열
필수: 예
설명: 생성 요청 콘텐츠를 담는 배열입니다.

Content 객체 속성:

속성	유형	필수	설명
`parts`	배열	예	하나의 메시지를 구성하는 순서화된 콘텐츠 파트

Part 객체 속성:

속성	유형	필수	설명
`text`	문자열	예 (이미지 생성 시)	원하는 이미지에 대한 텍스트 설명
`inline_data`	객체	예 (이미지 편집 시)	입력 이미지 데이터 (이미지 편집용)

`text` (parts 내)¶

유형: 문자열
필수: 예 (required for create image, also required for edit image)
설명: 원하는 이미지에 대한 텍스트 설명.
팁:
구체적이고 상세한 설명을 사용하세요
핵심 시각 요소를 포함하세요
원하는 예술 스타일을 명시하세요
구도와 시점을 설명하세요
이미지 편집 시 입력 이미지를 어떻게 수정할지 명확히 설명하세요

`inline_data` (parts 내, 이미지 편집용)¶

유형: 객체
필수: 예 (이미지 편집 시)
설명: 편집할 입력 이미지 데이터입니다.

InlineData 객체 속성 (요청):

속성	유형	필수	설명
`mime_type`	문자열	예	이미지 MIME 타입(예: "image/jpeg", "image/png")
`data`	문자열	예	Base64 인코딩 이미지 데이터

`generationConfig` (선택)¶

유형: 객체
필수: 아니오
설명: 생성 동작을 제어하는 설정 파라미터입니다.

GenerationConfig 객체 속성:

속성	유형	필수	설명
`responseModalities`	배열	아니오	응답에 포함할 모달리티 타입을 지정합니다(예: ["TEXT", "IMAGE"])
`imageConfig`	객체	아니오	이미지 생성 설정 파라미터

ImageConfig 객체 속성:

속성	유형	필수	설명
`aspectRatio`	문자열	아니오	이미지 종횡비(예: "1:1", "16:9")
`imageSize`	문자열	아니오	이미지 크기(예: "2K", "4K")

📥 응답¶

성공 응답¶

`candidates`¶

유형: 배열
설명: 모델의 후보 응답 목록

Candidate 객체 속성:

속성	유형	설명
`content`	객체	모델이 반환한 생성 콘텐츠
`finishReason`	열거형	모델이 생성을 중단한 이유
`index`	정수	응답 후보 목록 내 후보 인덱스

Content 객체 속성:

속성	유형	설명
`parts`	배열	생성된 콘텐츠 파트(텍스트/이미지 포함 가능)
`role`	문자열	콘텐츠 생성 주체(보통 "model")

Part 객체 속성:

속성	유형	설명
`text`	문자열	텍스트 콘텐츠(선택, 설명 텍스트 포함 가능)
`inlineData`	객체	생성 이미지 데이터(선택)

InlineData 객체 속성:

속성	유형	설명
`mimeType`	문자열	이미지 MIME 타입(예: "image/png")
`data`	String	Base64 인코딩 이미지 데이터

FinishReason enum 값:

STOP: 모델의 자연스러운 종료 지점
MAX_TOKENS: 요청에서 지정한 최대 토큰 수 도달
SAFETY: 안전 사유로 시스템이 후보 응답 콘텐츠를 표시/차단
IMAGE_SAFETY: 생성 이미지가 안전 규정을 위반해 토큰 생성 중단
OTHER: 알 수 없는 이유

`usageMetadata`¶

유형: 객체
설명: 생성 요청의 토큰 사용량 메타데이터

UsageMetadata 객체 속성:

속성	유형	설명
`promptTokenCount`	정수	프롬프트의 토큰 수
`candidatesTokenCount`	정수	생성된 모든 후보 응답의 총 토큰 수
`totalTokenCount`	정수	생성 요청의 총 토큰 수
`promptTokensDetails`	배열	요청 입력에서 처리된 모달리티 목록
`candidatesTokensDetails`	배열	응답에 반환된 모달리티 목록

candidatesTokensDetails 객체 속성:

속성	유형	설명
`modality`	열거형	해당 토큰 수와 연결된 모달리티(TEXT, IMAGE 등)
`tokenCount`	정수	토큰 수

`modelVersion`¶

유형: 문자열
설명: 응답 생성에 사용된 모델 버전

`responseId`¶

유형: 문자열
설명: 각 응답을 식별하는 ID

`promptFeedback` (선택)¶

유형: 객체
설명: 콘텐츠 필터와 관련된 프롬프트 피드백

이미지 객체 예시¶

{
  "inlineData": {
    "mimeType": "image/png",
    "data": "..."
  }
}

🌟 모범 사례¶

프롬프트 작성 제안¶

명확하고 구체적인 설명을 사용하세요
중요한 시각적 디테일을 명시하세요
원하는 예술 스타일과 분위기를 설명하세요
구도와 시점 설명에 유의하세요
색상, 조명, 분위기 등의 디테일을 포함할 수 있습니다

파라미터 선택 제안¶

모델 선택
- gemini-2.5-flash-image: 고품질 이미지를 빠르게 생성하는 데 적합
- gemini-3-pro-image-preview: 이미지 생성 및 편집을 지원하며 기존 이미지 기반 편집 시나리오에 적합
프롬프트 최적화
- 상세하고 설명적인 텍스트를 사용하세요
- 구체적인 시각 요소와 스타일 요구사항을 포함하세요
- 모호하거나 지나치게 짧은 설명을 피하세요
- 이미지 편집 시 추가/삭제/교체 등 원하는 수정 내용을 명확히 설명하세요
안전 설정
- 적용 시나리오에 맞게 안전 임계값을 조정하세요

공통 이슈¶

이미지 생성 실패
- 프롬프트가 콘텐츠 정책을 준수하는지 확인
- API 키 권한 확인
- 요청 형식이 올바른지 확인하세요
결과가 기대와 다름
- 프롬프트 설명을 더 구체적이고 상세하게 최적화하세요
- 시각적 디테일과 스타일 설명을 더 추가하세요
- 다양한 설명 방식을 시도해보세요
안전 필터 이슈
- 안전 필터가 트리거되지 않도록 프롬프트를 수정하세요