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

API 콘솔

POST/v1/images/generations
키 보기

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

GPT Image 2

요청 ID gpt-image-2

프로토콜

인증

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

  • Authorization: Bearer YOUR_API_KEY

요청 매개변수

POST /v1/images/generations

필드유형필수 여부설명
modelstring필수이 모델 ID를 지정하세요 gpt-image-2.
promptstring필수생성할 이미지의 내용을 설명하세요.
sizestring선택1536x1024처럼 픽셀 크기를 사용하는 것이 좋습니다. auto 또는 16:9 같은 비율도 전달할 수 있으며, 비율 처리 방식은 엔드포인트에 따라 다를 수 있습니다. 기본값 1024x1024.
image_sizestring선택출력 해상도 등급입니다. 허용 값 1K, 2K, 4K. 생략하면 size에서 계산합니다. 기본값 1K.
qualitystring선택생성 품질 설정입니다. 허용 값 auto, low, medium, high.
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를 지정하세요 gpt-image-2.
promptstring필수참조 이미지에 적용할 변경 사항을 설명하세요.
sizestring선택1536x1024처럼 픽셀 크기를 사용하는 것이 좋습니다. auto 또는 16:9 같은 비율도 전달할 수 있으며, 비율 처리 방식은 엔드포인트에 따라 다를 수 있습니다. 기본값 1024x1024.
image_sizestring선택출력 해상도 등급입니다. 허용 값 1K, 2K, 4K. 생략하면 size에서 계산합니다. 편집 시 JSON 요청 본문에 지정하세요. 기본값 1K.
qualitystring선택생성 품질 설정입니다. 허용 값 auto, low, medium, high.
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를 반환합니다. 생략하면 결과를 기다립니다.

요청 예시

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": "gpt-image-2",
  "prompt": "A watercolor illustration of a paper lantern by a lake.",
  "size": "1536x1024",
  "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": "gpt-image-2",
  "prompt": "Change the background to a pale blue wall. Preserve the subject.",
  "image_urls": [
    "https://example.com/reference.png"
  ],
  "size": "1536x1024",
  "image_size": "1K"
}'

Images Edits · 이미지 업로드 및 편집

bash
curl -sS 'https://api.icodeeasy.cc/v1/images/edits' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=Change the background to a pale blue wall. Preserve the subject.' \
  -F 'size=1536x1024' \
  -F 'image[]=@/path/to/photo.png'

이미지 작업 조회

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

응답 및 작업

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": "gpt-image-2",
  "result_url": "https://example.com/generated-image.png"
}

주요 오류

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

응답 예제와 오류

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

기능 및 제한

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

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

관련 가이드

이미지 생성 API

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

모델 기능 카탈로그

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

가입하고 API Key 받기