이미지 생성 API

이미지 생성 및 편집 API는 OpenAI Images 프로토콜과 호환됩니다. 현재 gpt-image-2를 제공하며 text-to-image와 image-to-image를 모두 지원합니다. 과금은 토큰이 아니라 이미지 수와 quality tier를 기준으로 합니다.

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

/v1/images/generations - 이미지 생성. 참조 이미지가 없으면 text-to-image, 있으면 image-to-image입니다
/v1/images/edits - 참조 이미지를 사용한 이미지 편집. OpenAI 네이티브 edits 사용 방식과 호환됩니다

두 엔드포인트의 기능과 과금은 같습니다. 참조 이미지가 있으면 image-to-image, 없으면 text-to-image로 처리됩니다.

엔드포인트와 인증

POST https://jp.icodeeasy.cc/v1/images/generations
POST https://jp.icodeeasy.cc/v1/images/edits

예시는 공식 접속 도메인 https://jp.icodeeasy.cc를 사용합니다. 경로는 변경하지 마세요.

요청 헤더:

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

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

두 가지 요청 본문 형식

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

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

요청 파라미터

model (필수): 현재는 gpt-image-2만 지원합니다.
prompt (필수): 영어 또는 중국어 이미지 설명입니다. OpenAI가 콘텐츠 안전성 검토를 수행하며, 거부된 콘텐츠는 과금되지 않습니다.
n (기본값 1): 이미지 수입니다. 과금은 이미지 수에 따라 누적됩니다.
size (기본값 1:1): 출력 비율입니다. 아래를 참고하세요. auto는 1:1로 처리되며 1536x1024 같은 픽셀 문자열도 허용됩니다.
resolution (기본값 1k): 해상도 tier이며 1k 또는 2k입니다.
quality (과금 전용): low, medium, high, auto. 실제 출력에는 영향을 주지 않고 과금 가격만 결정합니다. 값이 없으면 medium입니다.
image_urls / image_input (선택, JSON): image-to-image용 참조 이미지이며 최대 16개까지 가능합니다. 공개 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.

1k와 2k 모두 모든 비율을 지원합니다.

동기 / 비동기 모드

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

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

	기본 동기	`?async=1` 비동기
Return timing	Waits tens of seconds until image is ready	Returns immediately (< 1 second)
Status code	`200`	`202`
Response body	`{"created":...,"data":[{"url":"..."}],"id":"..."}`	`{"status":"pending","task_id":"..."}`
How to get image	Returned in one response	Poll `GET /v1/images/tasks/{task_id}`

요청 예시

Minimal text-to-image, sync

curl -X POST https://jp.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"
  }'

Specify ratio and 2K

curl -X POST https://jp.icodeeasy.cc/v1/images/generations \
  -H "Authorization: Bearer sk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a corgi astronaut on the moon, cinematic",
    "size": "16:9",
    "resolution": "2k",
    "quality": "medium"
  }'

Image-to-image using image URL (JSON)

curl -X POST https://jp.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://jp.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://jp.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",
    "resolution": "2k",
    "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://jp.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://jp.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 16 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 quality tier로 고정되며 토큰과는 무관합니다:

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

quality가 과금 tier를 결정합니다. 값이 없으면 medium을 사용합니다. Usage Details에는 요청이 model = gpt-image-2로 기록되고 cost_breakdown에는 image_count, image_cost_rmb, image_urls가 포함되어 기록에서 링크를 복사하거나 이미지를 다운로드할 수 있습니다.

OpenAI Images API와의 차이

Model: only gpt-image-2; no gpt-image-1 or dall-e-3
Endpoints: generations and edits have the same capability and switch automatically based on whether reference images exist
size: aspect ratios such as 16:9 are recommended; pixel strings are also accepted
resolution: new field not present in OpenAI Images API, 1k or 2k
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) or image[] (multipart), up to 16 images, URLs and base64 can be mixed
비동기 모드: OpenAI에는 이 모드가 없습니다. 이 API는 ?async=1을 지원하고 task_id를 반환하며 /v1/images/tasks/{id}를 폴링해 결과를 가져옵니다
Task ID: responses include id / task_id for troubleshooting

가입하고 API Key 받기