메인 콘텐츠로 건너뛰기
POST
/
v1
/
images
/
generations
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "창가에 앉아 석양을 바라보는 주황색 고양이, 수채화 스타일",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "창가에 앉아 석양을 바라보는 주황색 고양이, 수채화 스타일",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA"
    }
  ]
}

​
Authorizations

​
Authorization
string
필수
모든 엔드포인트는 Bearer Token 인증이 필요합니다API 키 받기：API 키 관리 페이지 에서 API 키를 받으세요사용 시 요청 헤더에 다음을 추가：
Authorization: Bearer YOUR_API_KEY

​
Body

​
model
string
기본값:"gpt-image-2"
필수
이미지 생성 모델 이름gpt-image-2 로 고정
​
prompt
string
필수
이미지 생성을 위한 텍스트 설명
  • 한국어 / 영어 / 중국어 지원, 상세한 설명을 권장
  • 제출 전에 플랫폼의 민감어 / 안전 심사를 거칩니다. 위반 내용은 즉시 오류를 반환합니다
​
n
integer
기본값:"1"
생성할 이미지 장수범위：1
반드시 순수 숫자(예：1)를 입력하세요. 따옴표로 감싸지 마세요
​
size
string
기본값:"1:1"
이미지 생성 비율다음 비율 지원, auto 를 전달하면 서버에서 적절한 비율을 자동 선택합니다：
size유형
auto자동
1:1정사각형
3:2가로
2:3세로
4:3가로
3:4세로
5:4가로
4:5세로
16:9가로
9:16세로
2:1가로
1:2세로
3:1가로
1:3세로
21:9가로
9:21세로
1881x836 / 887x1774 같은 픽셀 크기도 직접 전달할 수 있습니다.
size 에 auto 를 전달하면 기본 비율은 1:1 입니다.
​
resolution
string
기본값:"1k"
출력 해상도 단계선택 가능 값：1k / 2k / 4ksize × resolution → 실제 픽셀 매핑：
size1k2k4k
1:11024×1024 / 1254×12542048×20482880×2880
3:21536×10242048×13603520×2336
2:31024×15361360×20482336×3520
4:31024×7682048×15363312×2480
3:4768×10241536×20482480×3312
5:41280×1024 / 1448×10862560×20483216×2576
4:51024×1280 / 1122×14022048×25602576×3216
16:91536×864 / 1672×9412048×11523840×2160
9:16864×1536 / 941×16721152×20482160×3840
2:12048×1024 / 1774×8872688×13443840×1920
1:21024×2048 / 887×17741344×26881920×3840
3:11881×836 / 1536×5123072×10243840×1280
1:3887×1774 / 512×15361024×30721280×3840
21:92016×864 / 1915×8212688×11523840×1648
9:21864×2016 / 821×19151152×26881648×3840
4K 는 위 15가지 비율을 지원합니다. 표의 픽셀 크기를 size 로 직접 전달할 수도 있습니다.
​
image_urls
array
참조 이미지 배열 (OpenAI 표준 필드). 전달하면 이미지-이미지 모드로 전환됩니다
기타 OpenAI 표준 필드(response_format, quality, style 등)는 현재 지원되지 않으며 무시됩니다. 작업 결과는 url 만 반환됩니다. base64 가 필요하면 직접 다운로드하여 변환하세요.
​
official_fallback
boolean
기본값:"false"
공식 채널을 폴백으로 사용할지 여부
  • false：사용 안 함 (기본값)
  • true：공식 채널 사용

​
사용 시나리오 예시

텍스트-이미지 (최소 요청) 
{
  "model": "gpt-image-2",
  "prompt": "창가에 앉아 석양을 바라보는 주황색 고양이, 수채화 스타일"
}
텍스트-이미지 (비율 지정 + 2K) 
{
  "model": "gpt-image-2",
  "prompt": "a corgi astronaut on the moon, cinematic, 8k",
  "size": "16:9",
  "resolution": "2k"
}
텍스트-이미지 (4K 출력) 
{
  "model": "gpt-image-2",
  "prompt": "별이 빛나는 하늘 아래의 고대 성",
  "size": "16:9",
  "resolution": "4k"
}
이미지-이미지 (참조 = URL) 
{
  "model": "gpt-image-2",
  "prompt": "이 사진을 수채화 스타일로 변환",
  "image_urls": [
    "https://example.com/photo.jpg"
  ]
}
이미지-이미지 (참조 = base64) 
{
  "model": "gpt-image-2",
  "prompt": "이 사진을 수채화 스타일로 변환",
  "image_urls": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}
이미지-이미지 (다중 참조 융합, URL + base64 혼합) 
{
  "model": "gpt-image-2",
  "prompt": "이 두 사진을 하나의 포스터로 융합",
  "size": "4:3",
  "resolution": "2k",
  "image_urls": [
    "https://example.com/photo-a.jpg",
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  ]
}

​
Response

​
code
integer
응답 상태 코드
​
data
array
응답 데이터 배열

​
작업 결과 조회

제출 성공 후 task_id 가 반환됩니다. GET /v1/tasks/{task_id} 로 작업 상태를 폴링하세요. 자세한 내용은 작업 조회 API 참조.

​
성공 응답 예시

{
  "code": 200,
  "data": {
    "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
    "status": "completed",
    "progress": 100,
    "created": 1776748674,
    "completed": 1776748726,
    "actual_time": 52,
    "cost": 0.05279,
    "estimated_time": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/xxxxxxxx-gpt_image_2_task_xxx_0.png"
          ],
          "expires_at": 1776835126
        }
      ]
    }
  }
}
이미지 가져오기：data.result.images[0].url[0]

​
작업 상태

상태의미
submitted제출됨
processing업스트림 처리 중
completed성공, result.images 사용 가능
failed실패, error.message 확인

​
폴링 권장사항

  • 첫 조회 지연：제출 후 10~20 초 기다린 뒤 첫 조회 실행
  • 조회 간격：3~5 초 권장, 밀리초 단위 폴링은 피하세요
  • 타임아웃 참고：이미지 1장은 보통 3060 초 내 완료 (실측 actual_time 4453s)
  • 배치 조회：여러 작업을 동시에 조회하려면 POST /v1/tasks/batch 사용, 본문 {"task_ids": ["task_xxx", "task_yyy"]}

​
주의사항

  1. 비동기 처리：제출 후 task_id 반환, /v1/tasks/{task_id} 를 폴링하여 최종 이미지 URL 획득
  2. 콘텐츠 심사：prompt 는 먼저 플랫폼의 민감어 / 안전 심사를 거치며, 위반 시 즉시 거부 & 과금되지 않음
  3. 결과 URL：플랫폼이 업스트림 임시 서명 링크를 자체 R2 오브젝트 스토리지로 미러링하여, 반환되는 것은 안정 링크이며 클라이언트에서 직접 접근 가능
  4. URL 유효기간：응답의 expires_at = completed + 24h 는 비즈니스 레이어 힌트 필드입니다. 빠르게 다운로드하거나 자체 CDN으로 전송하세요
  5. 비율 충돌：비율은 size 필드로만 전달하는 것을 권장. prompt 에서 비율을 중복 기재하면 업스트림 해석 충돌을 일으킬 수 있음
  6. 과금 규칙：해상도 단계(1K / 2K / 4K)에 따라 과금, 실패 및 심사 거부 시 과금되지 않음
  7. 4K 지원 비율：위 15가지 비율은 모두 4K 를 지원하며, 해당 픽셀 크기를 size 로 직접 전달할 수도 있습니다
  8. 작업 보존：task_id 는 데이터베이스에 기본 며칠간 보존됩니다 (TASK_RETENTION_DAYS 설정). 만료된 조회는 “작업이 존재하지 않거나 만료됨” 을 반환