주요 콘텐츠로 건너뛰기

이미지 생성

목적​

텍스트 프롬프트를 기반으로 AI 이미지를 생성합니다. 선택적으로 참조 이미지를 업로드하여 생성 결과의 스타일이나 구도를 참고할 수 있습니다.

메서드 및 경로​

POST /public/v1/generate/image

인증​

인증 페이지를 참고하세요. Bearer 토큰이 필요합니다.

필수 헤더:

Authorization: Bearer {your_api_key}

요청 필드​

필드명타입필수설명
promptstring예이미지 생성을 위한 텍스트 프롬프트
ai_modelstring예사용할 AI 모델. 가능한 값: GPT Image 1.5, GPT Image 2, Grok Imagine, Grok Imagine Pro, Nano Banana, Nano Banana 2, Nano Banana Pro
ref_imagesfile[]아니오참조 이미지 파일들 (multipart/form-data). AI 모델에 따라 최대 업로드 개수가 다릅니다

응답​

성공 응답 (200 OK):

{
  "job_id": "uuid-string"
}
필드타입설명
job_idstring생성된 작업의 고유 식별자. 작업 상태 조회로 결과를 조회합니다

오류 / 유효성 검사 규칙​

상황HTTP 상태에러 메시지
Invalid image file400"Invalid image file"
Grok Imagine 모델에서 ref_images 5개 초과400"The Grok Imagine model supports up to 5 ref_images."
Grok Imagine Pro 모델에서 ref_images 1개 초과400"The Grok Imagine Pro model supports up to 1 ref_images."
기타 모델에서 ref_images 10개 초과400"ref_images supports up to 10 images only"
인증 실패401유효하지 않은 API 키

참조 이미지 제한:

  • GPT Image 1.5: 최대 10개
  • Grok Imagine: 최대 5개
  • Grok Imagine Pro: 최대 1개
  • Nano Banana 계열: 최대 10개

비동기 작업 동작​

이 엔드포인트는 비동기 작업을 생성합니다. 요청 즉시 job_id를 반환하고, 실제 이미지 생성은 백그라운드에서 진행됩니다.

폴링 방법:

  1. 응답으로 받은 job_id를 저장합니다
  2. GET /public/v1/job/{job_id}를 폴링하여 상태를 확인합니다
  3. 상태가 Succeed가 되면 image_urls에서 결과를 확인합니다

상태 흐름: Pending → Succeed 또는 Failed

요청 예시​

cURL (참조 이미지 없이):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a beautiful sunset over mountains" \
-F "ai_model=GPT Image 1.5"

cURL (참조 이미지 포함):

curl -X POST "https://api.aetherforgeai.com/public/v1/generate/image" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=a cat in the style of the reference" \
-F "ai_model=Grok Imagine" \
-F "ref_images=@/path/to/ref1.jpg" \
-F "ref_images=@/path/to/ref2.jpg"