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

# GPT Image 2 이미지 생성

> - GPT Image 2 (gpt-image-2) 모델은 텍스트-이미지, 이미지-이미지, 이미지 편집 등 다양한 생성 모드를 지원합니다
- 비동기 처리 모드, 반환된 작업 ID로 [조회](/ko/api-manual/task-management/get-task-detail)
- 생성된 이미지 링크는 24시간 동안 유효하며, 즉시 저장해 주세요



## OpenAPI

````yaml ko/api-manual/image-series/gpt-image-2/gpt-image-2-image-generation.json POST /v1/images/generations
openapi: 3.1.0
info:
  title: gpt-image-2 API
  description: AI 모델을 사용하여 이미지 작업을 생성하며, 다양한 모델 및 파라미터 설정을 지원합니다
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.evolink.ai
    description: 프로덕션
security:
  - bearerAuth: []
tags:
  - name: 이미지 생성
    description: AI 이미지 생성 관련 API
paths:
  /v1/images/generations:
    post:
      tags:
        - 이미지 생성
      summary: gpt-image-2 API
      description: >-
        - GPT Image 2 (gpt-image-2) 모델은 텍스트-이미지, 이미지-이미지, 이미지 편집 등 다양한 생성 모드를
        지원합니다

        - 비동기 처리 모드, 반환된 작업 ID로
        [조회](/ko/api-manual/task-management/get-task-detail)

        - 생성된 이미지 링크는 24시간 동안 유효하며, 즉시 저장해 주세요
      operationId: createImageGenerationGptImage2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageGenerationRequest'
            examples:
              text_to_image:
                summary: 텍스트에서 이미지 (기본)
                value:
                  model: gpt-image-2
                  prompt: 바다 위의 화려하고 아름다운 석양
              text_to_image_hd:
                summary: 텍스트에서 이미지 (고해상도 16:9)
                value:
                  model: gpt-image-2
                  prompt: 황혼의 미래 도시 스카이라인의 시네마틱 와이드 샷
                  size: '16:9'
                  resolution: 4K
                  quality: high
                  'n': 1
              text_to_image_pixel:
                summary: 텍스트에서 이미지 (명시적 픽셀)
                value:
                  model: gpt-image-2
                  prompt: 미니멀리스트 로고 디자인
                  size: 1024x1024
                  quality: medium
              image_edit:
                summary: 이미지에서 이미지 / 편집
                value:
                  model: gpt-image-2
                  prompt: 그녀 옆에 귀여운 고양이를 추가해주세요
                  size: '1:1'
                  resolution: 1K
                  quality: medium
                  image_urls:
                    - https://example.com/input.png
                  callback_url: https://your-domain.com/webhook/image-done
              image_inpaint:
                summary: 인페인팅(마스크 사용)
                value:
                  model: gpt-image-2
                  prompt: 하늘을 별이 빛나는 밤하늘로 바꿔주세요
                  size: '1:1'
                  resolution: 1K
                  quality: medium
                  image_urls:
                    - https://example.com/input.png
                  mask_url: https://example.com/mask.png
              batch_generation:
                summary: 배치 생성
                value:
                  model: gpt-image-2
                  prompt: 픽셀 아트 스타일의 귀여운 로봇
                  size: '1:1'
                  resolution: 2K
                  quality: high
                  'n': 4
      responses:
        '200':
          description: 이미지 작업이 성공적으로 생성되었습니다
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageGenerationResponse'
        '400':
          description: 잘못된 요청 파라미터
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: invalid_request
                  message: Invalid request parameters
                  type: invalid_request_error
        '401':
          description: 인증되지 않음, 토큰이 유효하지 않거나 만료됨
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: unauthorized
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: 할당량 부족, 충전 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: insufficient_quota
                  message: Insufficient quota. Please top up your account.
                  type: insufficient_quota
        '403':
          description: 액세스 거부됨
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: model_access_denied
                  message: 'Token does not have access to model: gpt-image-2'
                  type: invalid_request_error
        '429':
          description: 요청 빈도 초과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests, please try again later
                  type: rate_limit_error
        '500':
          description: 서버 내부 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: Internal server error
                  type: api_error
components:
  schemas:
    ImageGenerationRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: 이미지 생성 모델 이름, 공식 채널, 더 나은 안정성과 제어성, 상업적 시나리오에 적합
          enum:
            - gpt-image-2
          default: gpt-image-2
          example: gpt-image-2
        prompt:
          type: string
          description: >-
            생성할 이미지를 설명하는 프롬프트, 또는 입력 이미지를 편집하는 방법을 설명하는 프롬프트


            **제한:**

            - 최대 `32000`자 (유니코드 코드 포인트 기준, 한/중/일/영 등 모두 지원)

            - 프롬프트가 `8000` tokens를 초과하면 생성된 이미지가 기대와 다를 수 있으므로 프롬프트를 줄이는 것을
            권장합니다
          example: 바다 위의 화려하고 아름다운 석양
          maxLength: 32000
        image_urls:
          type: array
          description: >-
            이미지-이미지 및 이미지 편집 기능을 위한 참조 이미지 URL 목록


            **참고:**

            - 요청당 입력 이미지 수: `1~16`개

            - 단일 이미지 크기: 최대 `50MB`

            - 단일 이미지 픽셀: 너비 × 높이 최대 `178,956,970` px

            - 단일 이미지 변 길이: 너비 / 높이 모두 `23170` px 이하 (초과 시 오류가 발생할 수 있습니다)

            - 지원 형식: `.jpeg`, `.jpg`, `.png`, `.webp`

            - 이미지 URL은 서버에서 직접 접근 가능하거나, 접근 시 직접 다운로드되어야 합니다 (일반적으로 `.png`,
            `.jpg` 등 이미지 확장자로 끝나는 URL)

            - 이미지-이미지 / 이미지 편집 시나리오에서는 전달된 참조 이미지 자체도 추가 이미지 입력 토큰을 소모합니다
          items:
            type: string
            format: uri
          example:
            - https://example.com/image1.png
            - https://example.com/image2.png
        mask_url:
          type: string
          format: uri
          description: >-
            인페인팅 마스크 URL — 참조 이미지에서 다시 생성할 영역을 표시합니다. **이미지 편집 모드에서만 작동**합니다(반드시
            `image_urls`와 함께 사용). 순수한 텍스트-투-이미지 요청에서는 마스크가 조용히 무시됩니다.


            **형식 요구사항:**

            - **알파 채널이 있는 PNG여야 합니다**: 투명 픽셀(`alpha < 255`) = 다시 생성할 영역, 불투명 픽셀
            = 보존됨

            - **마스크 크기는 참조 이미지와 정확히 일치**해야 합니다(너비 × 높이, 픽셀 단위)

            - 요청당 마스크는 1개만 지원


            **참고:**

            - `image_urls`에 최소 1장의 참조 이미지가 필요합니다. 마스크만 보내면 효과가 없습니다

            - 자주 발생하는 오류:
                - `Invalid mask image format - mask image missing alpha channel`: 업로드한 이미지에 알파 채널이 없습니다(JPEG, 불투명 PNG 등). 투명 영역이 있는 PNG로 다시 내보내세요.
                - `Invalid mask image format - mask size does not match image size`: 마스크와 참조 이미지의 크기가 일치하지 않습니다. 마스크를 참조 이미지와 동일한 픽셀 크기로 조정하세요.
          example: https://example.com/mask.png
        size:
          type: string
          description: >-
            생성 이미지 크기. **비율 형식**과 **명시적 픽셀 형식** 두 가지를 지원하며, 기본값은 `auto`


            **① 비율 형식 (권장, 15가지)**


            - `1:1`: 정사각형

            - `1:2` / `2:1`: 극단 세로 / 가로

            - `1:3` / `3:1`: 초 세로 / 가로 (3:1 경계)

            - `2:3` / `3:2`: 표준 세로 / 가로

            - `3:4` / `4:3`: 클래식 세로 / 가로

            - `4:5` / `5:4`: 소셜 미디어 일반

            - `9:16` / `16:9`: 모바일 / 데스크톱 와이드스크린

            - `9:21` / `21:9`: 울트라와이드


            **② 명시적 픽셀 형식**: `WxH` (또는 `W×H`), 예: `1024x1024`, `1536x1024`,
            `3840×2160`


            - 가로·세로 모두 `16`의 배수여야 함

            - 각 변 범위: `[16, 3840]`

            - 픽셀 예산: `655,360 ≤ width × height ≤ 8,294,400` (약 0.65 MP ~ 8.29
            MP)

            - 종횡비: `≤ 3:1`


            **③ `auto`**: 모델이 자동으로 크기를 결정 (이 경우 `resolution`은 적용되지 않음)


            **초과 처리:**

            - 비율 + `resolution` 조합이 픽셀 예산을 초과하면 비율을 유지한 채 자동으로 상한까지 축소됩니다 (예: 4K
            2:1 → 3840×1920)
          default: auto
          example: auto
        resolution:
          type: string
          description: >-
            해상도 티어 단축 파라미터. `size`가 비율 형식일 때만 유효하며, 명시적 픽셀 형식에서는 이 필드가 무시됩니다


            **픽셀 버짓 규칙** (목표 총 픽셀 수와 `size` 비율에서 너비와 높이를 산출하며 16의 배수로 정렬됩니다):


            - `1K`: ~1 MP (1024² = 1,048,576 픽셀)

            - `2K`: ~4 MP (2048² = 4,194,304 픽셀)

            - `4K`: ~8.29 MP (3840×2160 = 8,294,400 픽셀, 최대값)


            **가로 / 정사각형 실제 출력 크기** (세로 크기는 대응하는 가로의 폭과 높이를 바꾼 것, 예: `2:3` =
            `3:2` 반전):


            | 비율 | 1K | 2K | 4K |

            |---|---|---|---|

            | `1:1` | 1024×1024 | 2048×2048 | 2880×2880 |

            | `2:1` | 1456×720 | 2896×1456 | 3840×1920 \* |

            | `3:1` | 1776×592 | 3552×1184 | 3840×1280 \* |

            | `3:2` | 1248×832 | 2512×1680 | 3520×2352 |

            | `4:3` | 1184×880 | 2368×1776 | 3312×2480 \* |

            | `5:4` | 1152×912 | 2288×1824 | 3216×2576 |

            | `16:9` | 1360×768 | 2736×1536 | 3840×2160 (UHD) |

            | `21:9` | 1568×672 | 3136×1344 | 3840×1632 \* |


            \* 는 픽셀 예산 초과로 비율을 유지한 채 자동 축소된 조합을 나타냅니다. 값은 대소문자를 구분하지 않습니다.
          enum:
            - 1K
            - 2K
            - 4K
          default: 1K
          example: 1K
        quality:
          type: string
          description: |-
            렌더링 품질. 모델의 "사고 깊이"를 제어하며 출력 토큰 수와 비용에 직접적인 영향을 미칩니다. 기본값 `medium`

            | 값 | 타일 기수 | 상대 비용 (1024²) |
            |---|---|---|
            | `low` | 16 | ~0.11× |
            | `medium` | 48 | 1.0× |
            | `high` | 96 | ~4.0× |
          enum:
            - low
            - medium
            - high
          default: medium
          example: medium
        'n':
          type: integer
          description: |-
            생성할 이미지 개수, 각각 독립적으로 과금됩니다

            **참고:**
            - 텍스트 입력 토큰은 `n`에 비례하여 확대됩니다
          minimum: 1
          maximum: 10
          default: 1
          example: 1
        callback_url:
          type: string
          description: >-
            작업 완료 후 HTTPS 콜백 주소


            **콜백 타이밍:**

            - 작업이 완료, 실패 또는 취소될 때 트리거됨

            - 과금 확인 완료 후 전송


            **보안 제한:**

            - HTTPS 프로토콜만 지원

            - 내부 IP 주소로의 콜백 금지 (127.0.0.1, 10.x.x.x, 172.16-31.x.x, 192.168.x.x
            등)

            - URL 길이는 `2048`자를 초과할 수 없음


            **콜백 메커니즘:**

            - 타임아웃: `10`초

            - 실패 시 최대 `3`회 재시도 (`1`초/`2`초/`4`초 후 재시도)

            - 콜백 응답 본문 형식은 작업 조회 API 응답 형식과 동일

            - 콜백 주소가 2xx 상태 코드를 반환하면 성공으로 간주, 다른 상태 코드는 재시도를 트리거
          format: uri
          example: https://your-domain.com/webhooks/image-task-completed
    ImageGenerationResponse:
      type: object
      properties:
        created:
          type: integer
          description: 작업 생성 타임스탬프
          example: 1757156493
        id:
          type: string
          description: 작업 ID
          example: task-unified-1757156493-imcg5zqt
        model:
          type: string
          description: 실제 사용된 모델 이름
          example: gpt-image-2
        object:
          type: string
          enum:
            - image.generation.task
          description: 구체적인 작업 유형
        progress:
          type: integer
          description: 작업 진행률 (0-100)
          minimum: 0
          maximum: 100
          example: 0
        status:
          type: string
          description: 작업 상태
          enum:
            - pending
            - processing
            - completed
            - failed
          example: pending
        task_info:
          $ref: '#/components/schemas/TaskInfo'
          description: 비동기 작업 정보
        type:
          type: string
          enum:
            - text
            - image
            - audio
            - video
          description: 작업 출력 유형
          example: image
        usage:
          $ref: '#/components/schemas/Usage'
          description: 사용량 및 과금 정보
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: 오류 코드 식별자
            message:
              type: string
              description: 오류 설명
            type:
              type: string
              description: 오류 유형
    TaskInfo:
      type: object
      properties:
        can_cancel:
          type: boolean
          description: 작업 취소 가능 여부
          example: true
        estimated_time:
          type: integer
          description: 예상 완료 시간(초)
          minimum: 0
          example: 100
    Usage:
      type: object
      description: 사용량 및 과금 정보
      properties:
        billing_rule:
          type: string
          description: 과금 규칙
          enum:
            - per_call
            - per_token
            - per_second
          example: per_call
        credits_reserved:
          type: number
          description: 예상 소비 크레딧 수
          minimum: 0
          example: 2.5
        user_group:
          type: string
          description: 사용자 그룹 카테고리
          example: default
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##모든 API는 Bearer Token 인증이 필요합니다##

        **API Key 받기:**

        [API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 받으세요

        **요청 헤더에 추가:**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````