이미지 모델고급 사용자업데이트
POST/v1/images/generations

API 콘솔

POST/v1/images/generations
키 보기

입력한 키로 실제 요청을 보내며 일반 API 요금이 적용됩니다.

Gemini 2.5 Flash Image

요청 ID gemini-2.5-flash-image

프로토콜

인증

요청에는 API 키 관리의 API 키가 필요합니다. JSON 요청은 Content-Type: application/json을 지정하세요.

  • Authorization: Bearer YOUR_API_KEY
  • Gemini · x-goog-api-key: YOUR_API_KEY

요청 매개변수

POST /v1/images/generations

필드유형필수 여부설명
modelstring필수이 모델 ID를 지정하세요 gemini-2.5-flash-image.
promptstring필수생성할 이미지의 내용을 설명하세요.
aspect_ratiostring선택출력 이미지의 가로세로 비율입니다. 예시는 1:1 또는 16:9입니다. 생략하면 size에서 계산합니다. 기본값 1:1.
image_sizestring선택출력 해상도 등급입니다. 허용 값 1K. 기본값 1K.
ninteger선택요청당 이미지 수입니다. 결과 하나를 받으려면 1을 지정하세요. 기본값 1.
image_urlsstring[]선택JSON 참조 이미지 배열입니다. 각 항목은 공개 HTTPS 이미지 URL 또는 Base64 이미지 data URL입니다. 호환 필드 image_input. 참조 이미지 한도 4.
?asyncstring선택URL 쿼리 매개변수입니다. 1, true, yes를 지정하면 202와 task_id를 반환합니다. 생략하면 결과를 기다립니다.

POST /v1/images/edits

필드유형필수 여부설명
modelstring필수이 모델 ID를 지정하세요 gemini-2.5-flash-image.
promptstring필수참조 이미지에 적용할 변경 사항을 설명하세요.
aspect_ratiostring선택출력 이미지의 가로세로 비율입니다. 예시는 1:1 또는 16:9입니다. 생략하면 size에서 계산합니다. 기본값 1:1. 편집 시 JSON 요청 본문에 지정하세요.
image_sizestring선택출력 해상도 등급입니다. 허용 값 1K. 편집 시 JSON 요청 본문에 지정하세요. 기본값 1K.
ninteger선택요청당 이미지 수입니다. 결과 하나를 받으려면 1을 지정하세요. 기본값 1.
image_urlsstring[]조건부JSON 참조 이미지 배열입니다. 각 항목은 공개 HTTPS 이미지 URL 또는 Base64 이미지 data URL입니다. 호환 필드 image_input. 참조 이미지 한도 4. JSON으로 편집할 때는 최소 한 장을 지정하세요.
image[]file[]조건부multipart/form-data로 편집할 때 최소 한 장을 업로드하고 여러 장은 같은 필드를 반복하세요. 단일 파일에는 image도 사용할 수 있습니다. 참조 이미지 한도 4.
?asyncstring선택URL 쿼리 매개변수입니다. 1, true, yes를 지정하면 202와 task_id를 반환합니다. 생략하면 결과를 기다립니다.

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

필드유형필수 여부설명
model (path)string필수URL 경로의 모델 ID에 gemini-2.5-flash-image를 사용하세요.
contentsobject[]필수대화 내용을 순서대로 보냅니다. 각 항목의 입력 조각은 parts에 넣습니다.
contents[].rolestring선택메시지 역할입니다. 사용자 입력은 user, 이전 모델 메시지는 model을 사용합니다.
contents[].partsobject[]필수콘텐츠 항목 안의 부분 배열입니다. 텍스트 부분에는 text를 사용합니다.
contents[].parts[].inlineDataobject조건부인라인 미디어 객체입니다. mimeType과 Base64로 인코딩한 data를 지정합니다. 지원 미디어는 모델과 엔드포인트에 따라 다릅니다.
systemInstructionobject선택시스템 지침 객체입니다. 지침 텍스트를 parts[].text에 넣습니다.
generationConfig.maxOutputTokensinteger선택출력 토큰 수의 상한입니다. 허용 범위는 모델과 엔드포인트에 따라 다릅니다.
generationConfig.responseModalitiesstring[]선택출력 모달리티 목록입니다. 이미지를 요청하려면 ["IMAGE"]를 지정하세요.

요청 예시

API Key를 로컬 환경 변수 ICODEEASY_API_KEY에 설정하고 직접 HTTP 호출을 허용하는 엔드포인트를 선택하세요. 특정 클라이언트가 필요한 경우 해당 설정 가이드를 따르세요.

예시의 미디어 URL 및 에셋 ID를 유효한 내 에셋으로 바꾸세요.

Images Generations

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/generations' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "gemini-2.5-flash-image",
  "prompt": "A watercolor illustration of a paper lantern by a lake.",
  "aspect_ratio": "16:9",
  "image_size": "1K"
}'

Images Edits

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/edits' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "gemini-2.5-flash-image",
  "prompt": "Change the background to a pale blue wall. Preserve the subject.",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "aspect_ratio": "16:9",
  "image_size": "1K"
}'

Gemini generateContent

bash
curl -sS 'https://api.icodeeasy.cc/v1beta/models/gemini-2.5-flash-image:generateContent' \
  -H "x-goog-api-key: $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "A watercolor illustration of a paper lantern by a lake."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "IMAGE"
    ]
  }
}'

Gemini generateContent · JSON

이미지 작업 조회

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

응답 및 작업

/v1/images/generations · /v1/images/edits

HTTP 200 · 동기 요청 성공

?sync=1을 사용하면 data[].url에서 생성한 이미지 URL을 읽을 수 있습니다. created는 Unix 초 타임스탬프이며 id는 작업 ID입니다.

json
{
  "id": "d142c93a-de26-40c9-be62-0de840d10960",
  "created": 1781599773,
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

HTTP 202 · 비동기 요청 접수

json
{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "pending"
}

?async=1을 사용하면 같은 API 키로 GET /v1/images/tasks/{task_id}를 반복 조회하세요. status는 pending, completed 또는 failed입니다. 완료되면 result_url에서 이미지 URL을 읽으세요.

HTTP 200 · 완료 작업 조회

json
{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gemini-2.5-flash-image",
  "result_url": "https://example.com/generated-image.png"
}

주요 오류

조회 결과가 failed이면 error를 확인하세요. error_detail이 있으면 다시 제출하기 전에 retryable을 확인하세요.

응답 예제와 오류

Gemini generateContent · JSON

candidates[].content.parts[]에서 inlineData가 있는 부분을 읽으세요. data를 Base64 디코딩하고 mimeType으로 이미지 형식을 확인하세요.

json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "BASE64_IMAGE_DATA"
            }
          }
        ]
      }
    }
  ]
}

전체 연동 가이드 · 요청 필드, 작업 상태 및 응답 형식은 전체 API 가이드를 참고하세요.

기능 및 제한

  • text_to_image · 지원
  • image_to_image · 지원
  • image_editing · 지원
  • native_generation · 지원
  • reference_images · 조건부 지원 — 지원되는 요청 형식으로 유효한 참조 이미지를 제공해야 합니다
  • 제한 참조 이미지: 최대 4개 · 해상도: 1k

호환 별칭 및 은퇴 리디렉션

  • gemini-2.5-flash-image-preview → gemini-2.5-flash-image (별칭)

모델 기능 카탈로그 · 가격 보기

관련 가이드

이미지 생성 API

OpenAI 호환 API로 이미지를 생성하거나 편집합니다. 프롬프트, 크기, 참고 이미지를 보내고 동기 결과를 읽거나 비동기 작업 상태를 조회합니다.

Gemini generateContent

Gemini 네이티브 API에서 JSON 응답이나 SSE 스트림을 받습니다. 모델 ID는 경로에, 입력 텍스트는 contents[].parts[]에 지정합니다.

모델 기능 카탈로그

공개 텍스트, 이미지 및 동영상 모델의 정규화된 요청 ID, 호환 프로토콜, 지원 클라이언트, 도구 호출, 미디어 입력·출력 기능, 제한 사항과 검토 날짜를 비교합니다.

가입하고 API Key 받기