이미지 생성 API

OpenAI Images 호환 API로 이미지 생성, 편집, 비동기 작업 조회를 할 수 있습니다.

엔드포인트와 인증

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/edits
GET  https://api.icodeeasy.cc/v1/images/tasks/{task_id}

일부 모델은 generations에서도 참조 이미지를 받습니다. edits에는 편집을 지원하는 모델을 사용하세요.

기본 Base URL은 https://api.icodeeasy.cc입니다. https://jp.icodeeasy.cc와 https://sg.icodeeasy.cc는 백업 / fallback 도메인이며 전환할 때 경로는 그대로 사용합니다.

요청 헤더:

• Authorization: Bearer <your API Key> (필수, sk_로 시작)
• Content-Type: JSON 요청은 application/json, 파일 업로드 요청은 multipart/form-data

아래 예제를 실행하기 전에 터미널에서 환경 변수 ICODEEASY_API_KEY를 설정하세요.

/v1 접두사 없는 POST /images/generations와 POST /images/edits도 허용되며 동일하게 동작합니다.

동기 / 비동기 모드

기본 동기 모드: 이미지 생성이 완료될 때까지 요청이 대기하고 OpenAI 호환 data[].url을 반환합니다.

비동기 모드: URL에 ?async=1을 추가합니다(true, yes도 허용). API는 즉시 task_id를 반환하고 결과는 폴링으로 가져옵니다. 긴 연결을 유지하고 싶지 않거나 진행 상태 처리, 배치 제출이 필요할 때 사용하세요.

요청 예시

GPT Image 2 텍스트 이미지 생성 (동기)

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "an orange cat sitting on a windowsill watching the sunset, watercolor style"
  }'

Gemini 3.x로 비율과 2K 지정

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }'

두 가지 요청 본문 형식

API는 두 가지 요청 본문 형식을 지원합니다:

1. JSON (Content-Type: application/json): 참조 이미지를 URL 또는 base64 data URL로 image_urls에 넣습니다. 가장 일반적인 형식입니다.
2. multipart/form-data: 참조 이미지를 image[] 파일로 업로드하고 다른 파라미터는 폼 필드에 넣습니다. OpenAI 네이티브 edits 사용 방식과 맞으며 로컬 파일 업로드에 적합합니다.

Image-to-image using image URL (JSON)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "size": "1536x1024",
    "image_urls": ["https://example.com/photo.png"]
  }'

Image-to-image uploading a local file (multipart)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=make this person 70 years old" \
  -F "size=1536x1024" \
  -F "image[]=@/path/to/photo.png"

Image-to-image with multiple references (URL + base64 mixed)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "merge these two photos into a poster",
    "size": "4:3",
    "image_urls": [
      "https://example.com/photo-a.jpg",
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    ]
  }'

비동기 편집 요청 보내기

curl -X POST "https://api.icodeeasy.cc/v1/images/edits?async=1" \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "make this person 70 years old",
    "image_urls": ["https://example.com/photo.png"]
  }'
# -> {"status":"pending","task_id":"d142c93a-..."}

HTTP 202 응답의 task_id를 저장한 뒤 작업 상태를 조회해 결과를 가져오세요.

응답 구조

Sync success (HTTP 200, OpenAI Images compatible):

{
  "id": "3e0c77bb-9cbd-4c44-9549-bff1b4060623",
  "created": 1781599773,
  "data": [
    {
      "url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/3e0c77bb-...-1.png"
    }
  ]
}

Async submit (HTTP 202):

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

이미지 작업 상태 조회

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

Async task query (GET /v1/images/tasks/{task_id}):

{
  "task_id": "d142c93a-de26-40c9-be62-0de840d10960",
  "status": "completed",
  "model": "gpt-image-2",
  "cost": 0.2,
  "result_url": "https://api.icodeeasy.cc/v1/images/files/gpt-image-2/20260616/d142c93a-...-1.png"
}

• status: pending / completed / failed
• data[].url / result_url: image URL, usable directly in <img src>
• id / task_id: task ID for support troubleshooting

API는 항상 URL을 반환하며 response_format: b64_json은 지원하지 않습니다. 바이트가 필요하면 직접 이미지를 다운로드하세요.

작업 조회가 HTTP 200을 반환해도 status를 확인합니다. failed이면 error가 사용자에게 표시할 설명입니다. error_detail이 있으면 type, message, retryable, charged와 선택 항목인 code, moderation_stage, categories를 확인할 수 있습니다. retryable을 보고 새 작업을 만들지 결정하세요. 필드가 없으면 재제출 전에 오류를 확인합니다. HTTP 404이면 작업 ID와 요청한 계정을 확인하세요.

이미지 URL 동작

data[].url looks like https://api.icodeeasy.cc/v1/images/files/gpt-image-2/YYYYMMDD/<id>-<seq>.png:

• 직접 열기: GET은 302를 반환하고 실제 이미지 URL로 리디렉션합니다
• 강제 다운로드: ?download=1을 추가합니다
• 장기 사용 가능: API가 반환한 I Code Easy URL을 저장하세요. 302 리디렉션 대상은 바뀔 수 있습니다.
• 접근 제어: 이 경로는 API Key가 필요하지 않습니다. 전체 링크 자체가 자격 증명입니다. 전체 URL을 가진 누구나 이미지를 다운로드할 수 있으므로 생성 결과 링크를 공개하지 마세요.

동기 처리와 타임아웃

기본 동기 모드에서는 이미지가 준비될 때까지 요청이 열린 상태로 유지됩니다:

• 권장 클라이언트 HTTP timeout: 최소 200초
• 이미지 1장은 보통 30~60초가 걸립니다. image-to-image, 2K, 여러 이미지는 더 오래 걸릴 수 있습니다
• 긴 연결에서 기다리고 싶지 않다면 비동기 모드(?async=1)로 task_id를 받고 나중에 폴링하세요

오류 응답

Error bodies use:

{
  "error": {
    "type": "server_error",
    "message": "...",
    "provider": "icodeeasy.cc"
  }
}

Common statuses:

• 400 invalid_request_error: 지원하지 않는 비율, 선택한 모델 또는 모드의 한도를 넘는 참조 이미지, HTTPS가 아닌 URL, 잘못된 base64 등
• 401 authentication_error: missing or invalid API Key
• 402 payment_required: insufficient balance or exhausted monthly quota
• 429 rate_limit_error: rate limit exceeded
• 5xx: service temporarily unavailable or generation failed; retry later

실패한 요청은 과금되지 않으며 잔액도 차감되지 않습니다.

요청 파라미터

아래 파라미터는 정지 이미지 요청에 적용됩니다. GIF 요청에는 GPT Image 2.6 GIF 생성 섹션의 파라미터를 사용하세요.

• model (필수): 주요 모델 또는 GPT Image 2.6 정지 이미지 섹션의 모델 ID를 사용합니다.
• prompt (필수): 영어 또는 중국어 이미지 설명입니다. 업스트림이 콘텐츠 안전성 검토를 수행하며, 거부된 콘텐츠는 과금되지 않습니다.
• n (기본값 1): 이미지 수입니다. 과금은 이미지 수에 따라 누적됩니다. GPT Image 2를 실제 작업 총비용으로 정산할 때 이미지 수를 다시 곱하지 않습니다.
• size (기본값 1:1): 출력 비율입니다. 아래를 참고하세요. auto는 1:1로 처리되며 1536x1024 같은 픽셀 문자열도 허용됩니다.
• aspect_ratio (선택, 기본값 1:1): GPT Image 2.5 및 2.6의 출력 비율입니다. 예를 들어 16:9입니다.
• image_size (선택, 기본값 1K): GPT Image 2 / 2.5 / 2.6의 출력 해상도입니다. 1K, 2K, 4K를 지원합니다. Gemini의 지원 해상도는 해상도 섹션을 참고하세요.
• quality: GPT Image 2는 low / medium / high / auto를 지원하지만 품질별 요금은 없습니다. GPT Image 2.5는 이미지 수와 해상도별로 과금하며 별도 품질 설정이 없습니다. 기존 요청의 이 필드는 허용되지만 생성 파라미터나 가격에 영향을 주지 않습니다.
• image_urls / image_input (선택, JSON): 이미지 생성에 사용하는 참조입니다. 최대 개수는 모델과 모드에 따라 다릅니다. 주요 모델의 Seedream 4종, FLUX 3, GPT Image 2.6은 최대 8개, 같은 표의 Gemini 모델은 최대 4개입니다. 공개 https://... URL 또는 data:image/...;base64,... 값을 사용할 수 있고 혼합도 가능합니다. 두 필드는 별칭입니다.
• image[] (선택, multipart): image-to-image용 참조 이미지 파일입니다. 여러 파일을 허용하며 image_urls의 파일 업로드 형식과 같습니다.

참조 이미지 참고: URL은 반드시 https://를 사용해야 합니다(http는 거부됨). base64는 유효한 data:image/*;base64, 값이어야 합니다.

지원 비율과 해상도

지원되는 size 비율: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 2:1 / 1:2 / 21:9 / 9:21 / auto.

GPT Image 2.5의 aspect_ratio: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 5:4 / 4:5 / 16:9 / 9:16 / 21:9.

gemini-2.5-flash-image는 1k만 지원합니다. 표의 Gemini 3.x는 1k / 2k / 4k를 지원합니다. gpt-image-2는 size로 출력 비율 또는 픽셀 크기를 지정하며 공개된 해상도 tier는 없습니다.

OpenAI Images API와의 차이

• 모델 ID와 편집 지원 여부는 주요 모델을 참고하세요.
• 출력 비율, 해상도, 참조 이미지 형식은 요청 파라미터에서 확인하세요.
• 결과는 이미지 URL로 반환됩니다. 비동기 모드에서는 작업 ID를 저장한 뒤 결과를 조회하세요.

주요 모델

표의 검증된 16개 모델은 모두 generations에서 텍스트로 이미지를 생성할 수 있습니다. 편집 엔드포인트 지원 여부는 표에서 확인하세요.

GPT Image 2, 2.5, 2.6 정지 이미지

세 버전 모두 1K, 2K, 4K 정지 이미지를 지원합니다. 텍스트로 이미지를 생성할 때는 POST /v1/images/generations를 사용하세요. 참조 이미지를 편집할 때는 POST /v1/images/edits의 image_urls에 공개 HTTPS URL 또는 data:image/...;base64,... 값을 전달하세요. Image 2.6은 참조 이미지를 최대 8장까지 지원합니다. Image 2.6의 2K 및 4K 정지 이미지에 사용하는 참조 이미지는 PNG, JPEG, WebP만 지원합니다.

image_size로 해상도를 선택하세요. Image 2는 size에 16:9 같은 비율을 지정합니다. Image 2.5와 2.6은 aspect_ratio를 사용할 수 있습니다. Image 2.6 정지 이미지는 output_format: "png"와 n: 1을 지정합니다.

GPT Image 2 동기 텍스트 이미지 생성은 요청 예시를 참고하세요.

GPT Image 2.5 텍스트 이미지 생성 (2K)

curl -X POST "https://api.icodeeasy.cc/v1/images/generations?sync=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "우주비행사 헬멧을 쓴 주황색 고양이, 영화 같은 조명",
    "aspect_ratio": "16:9",
    "image_size": "2K"
  }'

GPT Image 2.5 이미지 간 변환 (참조 이미지 편집)

curl -X POST "https://api.icodeeasy.cc/v1/images/edits?sync=1" \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "인물의 자세와 의상은 유지하고 배경을 석양 해변으로 변경",
    "aspect_ratio": "3:2",
    "image_size": "1K",
    "image_urls": ["https://example.com/photo.png"]
  }'

GPT Image 2.6 참조 이미지 편집 (4K)

아래 예시는 Sunburst를 사용합니다. Flare를 사용하려면 model을 gpt-image-2.6-flare로 바꾸세요. 예시 URL은 참조 이미지의 URL로 교체하세요.

curl -X POST 'https://api.icodeeasy.cc/v1/images/edits?async=1' \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst",
    "prompt": "배경을 옅은 파란색 벽으로 바꿔 주세요. 참조 이미지의 컵과 구도는 유지해 주세요.",
    "output_format": "png",
    "aspect_ratio": "16:9",
    "image_size": "4K",
    "n": 1,
    "image_urls": [
      "https://example.com/reference.png"
    ]
  }'

GPT Image 2.6 GIF 생성

gpt-image-2.6-flare와 gpt-image-2.6-sunburst는 POST /v1/images/generations에서 GIF를 생성할 수 있습니다. output_format: "gif", size: "auto", n: 1을 지정하면 크기와 프레임 설정이 자동으로 결정되며 GIF 한 개가 생성됩니다.

텍스트만으로 GIF를 생성할 때는 image_urls를 생략합니다. 참조 이미지를 사용하려면 공개 HTTPS URL 또는 data:image/...;base64,... 형식으로 최대 8장을 전달합니다.

아래 예시는 Flare를 사용합니다. 예시 URL을 참조 이미지 URL로 바꾸세요. Sunburst를 사용하려면 model을 gpt-image-2.6-sunburst로 지정하세요.

curl -X POST 'https://api.icodeeasy.cc/v1/images/generations?async=1' \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "참조 이미지의 종이 등불이 부드럽게 흔들리게 해 주세요. 원래 구도를 유지하고 자연스럽게 반복되도록 만들어 주세요.",
    "output_format": "gif",
    "size": "auto",
    "n": 1,
    "image_urls": [
      "https://example.com/reference.png"
    ]
  }'

비동기 요청은 task_id를 반환합니다. GET /v1/images/tasks/{task_id}에서 상태를 조회하고 완료 후 result_url에서 GIF를 다운로드하세요.

• 텍스트 GIF의 표준 요금은 결과당 ¥0.0833입니다. Flare에서 예비 서비스가 사용되면 결과당 ¥0.30입니다.
• 참조 이미지 GIF는 실제 사용량에 따라 과금됩니다. 최종 청구 금액은 사용 내역에서 확인할 수 있습니다.

FLUX 2 Pro / Max / Flex

해상도별 참고 가격(CNY / 장)입니다. 실제 생성 사용량으로 정산하며 최종 금액은 청구 내역에 표시됩니다: 요금은 출력 크기와 참조 이미지에 따라 달라집니다.

Seedream 시리즈

새 4개 모델은 기본 생성과 참조 이미지 편집을 지원하며 참조 이미지는 최대 8개입니다. size / aspect_ratio에 비율, image_size에 아래 해상도, image_input에 참조를 지정합니다. 작업당 한 장이며 여러 장은 별도 작업으로 처리합니다. 5 Flash/Pro 비율: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 2:1, 1:2, 21:9. 4.5/4.0은 9:21도 지원합니다. 4.0 프롬프트는 최대 1000자입니다. 레이어와 투명 배경 등 고급 기능은 제공하지 않습니다. 기존 Lite는 2K ¥0.30 / 3K ¥0.45를 유지합니다.

참고 가격이며 완료된 작업의 실제 생성 요금으로 정산합니다. 최종 금액은 사용 내역에서 확인하세요. Seedream 5 Pro만 해당: 두 번째 참조 이미지부터 장당 약 ¥0.01911이며 실제 작업 요금을 우선합니다.

FLUX 3 Image 및 Klein

flux-3-image와 flux-3-image-klein은 image_size로 768sq / 1K / 1.5K / 2K / 4K를, aspect_ratio로 1:1 / 9:16 / 16:9 / 2:3 / 3:2 / 4:5 / 5:4를 명시합니다. auto나 픽셀 크기를 보내지 마세요. 기존 FLUX 2의 한 변 2048픽셀 제한은 적용되지 않습니다. 참조 이미지는 image_input(URL 또는 base64 data URL)으로 최대 8개이며 영역 지정 편집은 지원하지 않습니다. 작업당 이미지 한 장을 생성하며 그리기 페이지의 여러 장 생성은 별도 작업으로 분리됩니다. Image는 seed를 지원하지 않으며 Klein은 0–4294967295의 seed를 지원합니다. 두 모델 모두 prompt_upsampling, style, negative_prompt를 지원하지 않습니다.

참고 가격이며 완료된 작업의 실제 생성 요금으로 정산합니다. 최종 금액은 사용 내역에서 확인하세요.

{
  "model": "flux-3-image",
  "prompt": "A watercolor landscape",
  "aspect_ratio": "16:9",
  "image_size": "4K",
  "image_input": []
}

과금

GPT Image 정지 이미지 요금과 GIF 과금 규칙을 참고하세요.

Gemini 이미지 모델은 모델별 고정 가격으로 과금됩니다:

Usage Details에는 실제 model로 기록되고 cost_breakdown에는 image_count, image_cost_rmb, image_urls가 포함되어 기록에서 링크를 복사하거나 이미지를 다운로드할 수 있습니다.