이미지 생성 API

이미지 API는 OpenAI Images 프로토콜과 호환됩니다. 아래는 선별·검증된 8개 모델입니다. 모든 모델은 generations에서 text-to-image를 지원하며, /edits는 명시된 모델에만 사용해야 합니다.

사용할 수 있는 엔드포인트는 두 가지입니다:

• /v1/images/generations - 이미지 생성. 일부 모델은 이 엔드포인트에서 참조 이미지도 받습니다
• /v1/images/edits - 아래 표에 명시된 모델의 이미지 편집. OpenAI 네이티브 edits 사용 방식과 호환됩니다

엔드포인트와 인증

POST https://api.icodeeasy.cc/v1/images/generations
POST https://api.icodeeasy.cc/v1/images/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

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

두 가지 요청 본문 형식

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

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

요청 파라미터

• model (필수): 위 표의 선별된 8개 모델 ID 중 하나를 사용합니다.
• prompt (필수): 영어 또는 중국어 이미지 설명입니다. 업스트림이 콘텐츠 안전성 검토를 수행하며, 거부된 콘텐츠는 과금되지 않습니다.
• n (기본값 1): 이미지 수입니다. 과금은 이미지 수에 따라 누적됩니다.
• size (기본값 1:1): 출력 비율입니다. 아래를 참고하세요. auto는 1:1로 처리되며 1536x1024 같은 픽셀 문자열도 허용됩니다.
• resolution (기본값 1k): Gemini 2.5는 1k만, 표의 Gemini 3.x는 1k / 2k / 4k를 지원합니다. gpt-image-2의 tier 선택에는 사용하지 마세요.
• quality (gpt-image-2 과금 전용): low, medium, high, auto. 실제 출력에는 영향을 주지 않고 gpt-image-2의 과금 가격만 결정합니다. Gemini 모델은 이 필드를 무시하고 모델별 고정 가격으로 과금됩니다.
• image_urls / image_input (선택, JSON): image-to-image용 참조 이미지이며 최대 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.

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

동기 / 비동기 모드

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

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

요청 예시

Minimal text-to-image, sync

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -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 sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k"
  }'

Gemini text-to-image

curl -X POST https://api.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "a futuristic coffee shop at sunrise, realistic photography",
    "size": "16:9",
    "resolution": "1k"
  }'

Image-to-image using image URL (JSON)

curl -X POST https://api.icodeeasy.cc/v1/images/edits \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -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 sk_xxxxxxxx" \
  -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 sk_xxxxxxxx" \
  -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..."
    ]
  }'

Async submit + polling

# 1) Submit and get task_id immediately
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",
    "prompt": "make this person 70 years old",
    "image_urls": ["https://example.com/photo.png"]
  }'
# -> {"status":"pending","task_id":"d142c93a-..."}

# 2) Poll until completed
curl "https://api.icodeeasy.cc/v1/images/tasks/d142c93a-..." \
  -H "Authorization: Bearer sk_xxxxxxxx"
# -> {"status":"completed","result_url":"https://...png","cost":0.2,...}

응답 구조

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" }

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은 지원하지 않습니다. 바이트가 필요하면 직접 이미지를 다운로드하세요.

이미지 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 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: invalid parameters, unsupported ratio, more than 4 reference images, non-https reference URL, invalid base64, and similar issues
• 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

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

과금

과금은 CNY 기준 이미지 수 x 모델 / tier로 고정되며 토큰과는 무관합니다.

gpt-image-2는 quality tier로 과금됩니다:

• low: CNY 0.10 / image
• medium / auto (default): CNY 0.20 / image
• high: CNY 0.40 / image

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

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

OpenAI Images API와의 차이

• Model: 위 표의 선별된 8개 모델 ID 중 하나를 사용합니다. gpt-image-1과 dall-e-3는 없습니다
• Endpoints: 모든 선별 모델은 generations를 지원하며, edits는 위 표에 명시된 모델만 지원합니다
• size: aspect ratios such as 16:9 are recommended; pixel strings are also accepted
• resolution: Gemini 2.5는 1k만, 표의 Gemini 3.x는 1k / 2k / 4k를 지원하며 gpt-image-2의 해상도 tier는 공개하지 않습니다
• quality: low, medium, high, or auto; billing only, different from OpenAI standard / hd
• response_format: b64_json is not supported; URLs are always returned
• Reference images: 위 표에 지원이 명시된 모델만 사용할 수 있으며, 지원 요청에서는 모델별 제한에 따라 image_urls / image_input (JSON) 또는 image[] (multipart)를 사용합니다
• 비동기 모드: OpenAI에는 이 모드가 없습니다. 이 API는 ?async=1을 지원하고 task_id를 반환하며 /v1/images/tasks/{id}를 폴링해 결과를 가져옵니다
• Task ID: responses include id / task_id for troubleshooting