메인 콘텐츠로 건너뛰기
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"
  }'

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

{
  "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"
이미지 생성 비율13가지 비율 지원：
  • 1:1 - 정사각형 (기본값)
  • 16:9 / 9:16 - 와이드 가로 / 세로
  • 4:3 / 3:4 - 표준 가로 / 세로
  • 3:2 / 2:3 - 클래식 가로 / 세로
  • 5:4 / 4:5 - 거의 정사각형 가로 / 세로
  • 2:1 / 1:2 - 와이드 가로 / 롱 세로
  • 21:9 / 9:21 - 초와이드 가로 / 초롱 세로
비율 표기만 지원합니다. 1024x1024 와 같은 픽셀 크기를 전달하면 build_request_failed: invalid size 오류가 발생합니다
​
image_urls
array
참조 이미지 배열 (OpenAI 표준 필드). 전달하면 이미지-이미지 모드로 전환됩니다
기타 OpenAI 표준 필드（response_format, quality, style 등）는 현재 지원되지 않으며 무시됩니다. 작업 결과는 url 만 반환됩니다. base64 가 필요하면 직접 다운로드하여 변환하세요.

​
사용 시나리오 예시

텍스트-이미지 (최소 요청) 
{
  "model": "gpt-image-2",
  "prompt": "창가에 앉아 석양을 바라보는 주황색 고양이, 수채화 스타일"
}
텍스트-이미지 (비율 지정) 
{
  "model": "gpt-image-2",
  "prompt": "a corgi astronaut on the moon, cinematic, 8k",
  "size": "16:9",
  "n": 1
}
이미지-이미지 (참조 = URL) 
{
  "model": "gpt-image-2",
  "prompt": "이 사진을 수채화 스타일로 변환",
  "size": "1:1",
  "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",
  "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,
    "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]

​
작업 상태

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

​
폴링 권장사항

  • 첫 조회 지연：제출 후 10~20 초 기다린 뒤 첫 조회 실행
  • 조회 간격：3~5 초 권장, 밀리초 단위 폴링은 피하세요
  • 타임아웃 참고：이미지 1장은 보통 3060 초 내 완료 (실측 actual_time 4452s)
  • 배치 조회：여러 작업을 동시에 조회하려면 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. 과금 규칙：성공한 이미지당 과금, 실패 및 심사 거부 시 과금되지 않음
  7. 작업 보존：task_id 는 데이터베이스에 기본 며칠간 보존됩니다 (TASK_RETENTION_DAYS 설정). 만료된 조회는 “작업이 존재하지 않거나 만료됨” 을 반환