이미지 생성

이미지 생성은 텍스트 프롬프트를 — 선택적으로 참조 이미지의 안내를 받아 — 한 장 이상의 이미지로 바꿔 줍니다. 네 시리즈에 걸친 열 개 모델이 하나의 요청 스키마와 하나의 엔드포인트 집합을 공유하며, model 필드로 모델을 선택합니다.

호출 방식은 세 가지입니다.

• 동기 — POST /v1/images/generation 은 이미지가 준비될 때까지 블로킹하며, 응답 본문에 모델의 원본 출력(base64 이미지 데이터)을 반환합니다.
• 비동기 — POST /v1/images/generation/async 는 taskId 를 즉시 반환합니다. 호스팅된 이미지 URL은 GET /v1/images/generation/tasks/{taskId} 를 폴링해서 가져오세요.
• 먼저 예상 — POST /v1/images/generation/estimate-credits 는 아무것도 소비하지 않고 크레딧 비용과 계정이 생성 가능한 상태인지를 반환합니다.

모델 선택

아래 표에서 모델을 고른 다음, 해당 시리즈 페이지에서 정확한 제한과 특이 사항, 예제를 확인하세요.

model 을 생략하면 gpt-image-2 가 기본값입니다. 표준 10종 비율은 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 — 네 가지 극단 비율을 제외한 전부입니다. 전체 규칙은 화면 비율을 참고하세요.

호출 흐름

요청 파라미터

아래 파라미터는 POST /v1/images/generation, POST /v1/images/generation/async, POST /v1/images/generation/estimate-credits 에 적용됩니다 — 세 엔드포인트가 하나의 요청 스키마를 공유합니다.

¹ provider 는 두 생성 엔드포인트에서 필수이고 estimate-credits 에서는 선택입니다. ² prompt 는 두 생성 엔드포인트에서 필수입니다. estimate-credits 에서는 비어 있거나 생략해도 됩니다(입력 token 예상치에만 영향을 줍니다).

화면 비율

전체 모델 목록에 걸쳐 14종의 비율이 있습니다. 그중 10종은 표준 비율로 대부분의 모델이 받아들이고, 4종은 극단 비율로 gemini-3.1-flash-image 와 seedream-5-0-pro 만 받아들입니다.

위의 스키마 기본값이 값을 이미 채워 넣지 않았을 때, aspectRatio 는 다음과 같이 결정됩니다.

이미지 크기

imageConfig.imageSize 는 1K, 2K(기본값), 4K 를 받습니다. 크레딧 비용은 모델과 크기에 따라 달라집니다.

크레딧 비용을 하드코딩하지 마세요 — 사용할 모델과 크기, 비율의 정확한 값은 estimate-credits를 호출해 확인하세요.

참조 이미지

참조 이미지는 생성을 유도합니다. 각 이미지는 URL(fileData) 또는 base64(inlineData) 중 하나로만 제공하고 둘 다 넣지 마세요. 배열은 모델의 상한 안으로 유지하세요.

스키마는 모든 모델에 대해 referenceImages 를 최대 14개로 제한합니다. 상한이 더 엄격한 시리즈는 초과분을 400 과 해당 상한을 밝히는 메시지로 거부합니다. fileData 와 inlineData 모두 받아들이는 MIME 타입은 image/png, image/jpeg, image/webp, image/heic, image/heif 입니다.

세 이미지 엔드포인트는 최대 25MB 의 JSON 본문을 받습니다 — base64 inlineData 가 그 안에 들어가야 하므로 플랫폼 기본값의 네 배입니다. base64는 파일 크기를 대략 3분의 1 정도 부풀리므로, 인라인으로 넣는 이미지는 원본 바이트 기준 합계 약 18MB 아래로 유지하거나, fileData 로 URL을 전달하세요.

이미지 생성(동기)

POST /v1/images/generation

이미지를 생성하고 준비될 때까지 블로킹합니다. 응답 본문은 모델의 원본 출력 — base64 이미지 데이터를 담은 JSON이며, 표준 { code, message, data } 엔벨로프가 아닙니다. 응답 형식을 참고하세요.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "16:9"
    }
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      provider: 'google',
      model: 'gemini-3-pro-image',
      prompt: 'An astronaut riding a horse on Mars, photorealistic',
      imageConfig: { imageSize: '2K', aspectRatio: '16:9' },
    }),
  },
)
const result = await response.json()
const image = result.candidates[0].content.parts[0].inlineData

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'provider': 'google',
        'model': 'gemini-3-pro-image',
        'prompt': 'An astronaut riding a horse on Mars, photorealistic',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '16:9'},
    },
)
result = response.json()
image = result['candidates'][0]['content']['parts'][0]['inlineData']

참조 이미지 사용

참조 이미지는 모든 엔드포인트에서 동일하게 동작합니다. 이미지가 이미 호스팅되어 있으면 fileData 를, 바이트를 메모리에 갖고 있으면 inlineData 를 사용하세요.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "fileData": {
          "fileUri": "https://example.com/character.png",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "Redraw this character in a watercolor style",
    "referenceImages": [
      {
        "inlineData": {
          "data": "'"$(base64 -w0 character.png)"'",
          "mimeType": "image/png"
        }
      }
    ],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "3:4" }
  }'

비동기 생성

오래 걸리거나 고해상도인 작업이라면 요청을 열어 둔 채 기다리지 말고, 작업을 제출한 뒤 결과를 폴링하세요.

비동기 작업 생성

POST /v1/images/generation/async

요청 본문은 동기 엔드포인트와 동일합니다. taskId 와 함께 202 를 즉시 반환하며, 생성은 백그라운드에서 진행되고 결과 이미지는 호스팅된 URL로 저장됩니다.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/async" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "model": "gemini-3-pro-image",
    "prompt": "An astronaut riding a horse on Mars, photorealistic",
    "imageConfig": { "imageSize": "4K", "aspectRatio": "16:9" }
  }'

응답(202):

{
  "code": 0,
  "message": "",
  "data": { "taskId": "65f0...", "status": "pending" }
}

작업 조회

GET /v1/images/generation/tasks/{taskId}

단일 작업의 상태와 결과를 폴링합니다. status 는 pending, generating, success, fail 중 하나입니다. 성공하면 images 에 호스팅된 결과 URL이 담깁니다.

curl "https://api.marswave.ai/openapi/v1/images/generation/tasks/65f0abc..." \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

{
  "code": 0,
  "message": "",
  "data": {
    "taskId": "65f0abc...",
    "status": "success",
    "images": [{ "url": "https://.../0.png", "mimeType": "image/png" }],
    "createdAt": 1750000000000,
    "completedAt": 1750000020000
  }
}

작업 목록 조회

GET /v1/images/generation/tasks

내 이미지 작업을 최신순으로 나열합니다.

curl "https://api.marswave.ai/openapi/v1/images/generation/tasks?page=1&pageSize=20&status=success" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "taskId": "65f0...",
        "status": "success",
        "images": [],
        "createdAt": 1750000000000,
        "completedAt": 1750000020000
      }
    ],
    "page": 1,
    "pageSize": 20,
    "total": 1
  }
}

크레딧 예상

POST /v1/images/generation/estimate-credits

주어진 설정의 크레딧 비용과 계정 잔액이 충분한지를, 크레딧을 소비하지도 모델을 호출하지도 않고 반환합니다. 생성 엔드포인트와 동일한 요청 본문을 받으며, 여기서는 provider 와 prompt 가 선택입니다.

curl -X POST "https://api.marswave.ai/openapi/v1/images/generation/estimate-credits" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "imageConfig": {
      "imageSize": "2K",
      "aspectRatio": "1:1"
    }
  }'

const response = await fetch(
  'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LISTENHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-image-2',
      imageConfig: { imageSize: '2K', aspectRatio: '1:1' },
    }),
  },
)
const { data } = await response.json()
console.log(data.credits, data.canGenerate)

import os
import requests

response = requests.post(
    'https://api.marswave.ai/openapi/v1/images/generation/estimate-credits',
    headers={'Authorization': f'Bearer {os.environ["LISTENHUB_API_KEY"]}'},
    json={
        'model': 'gpt-image-2',
        'imageConfig': {'imageSize': '2K', 'aspectRatio': '1:1'},
    },
)
data = response.json()['data']
print(data['credits'], data['canGenerate'])

예상 응답

표준 엔벨로프로 감싸집니다. data 객체는 다음과 같습니다.

{
  "code": 0,
  "message": "",
  "data": {
    "model": "gpt-image-2",
    "imageSize": "2K",
    "aspectRatio": "1:1",
    "credits": 6,
    "canGenerate": true,
    "requiresSubscription": false,
    "pricing": { "pricingVersion": "gpt-image-2-lite-fixed-2026-06-15", "mode": "fixed" },
    "warnings": []
  }
}

무료 생성

API key 호출은 ListenHub 및 Labnana 앱과 동일한 계정 단위 무료 할당량(freeUsages) 잔액을 사용합니다. 가입, 초대, 출석 체크로 할당량을 적립하고 API를 통해 소비합니다. 실시간 잔액은 GET /v1/user/subscription 으로 조회한 뒤 freeUsages 맵을 읽으세요.

해당 잔액이 0 보다 크면 1K 또는 2K 요청은 크레딧 대신 무료 생성 1회를 소비합니다. 잔액이 0 이 되면 같은 요청은 일반 크레딧 과금으로 되돌아갑니다.

gemini-3-pro-image 는 무료 할당량이 별도 실행 통로에서 도는 유일한 모델이며, 분기 처리에 쓸 자체 실패 메타데이터가 있습니다 — Nano Banana → relax 통로를 참고하세요.

응답 형식

동기 엔드포인트는 모델의 원본 출력을 그대로 반환합니다. 성공한 응답 본문에는 생성된 이미지가 base64 데이터로 들어 있습니다.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_ENCODED_IMAGE>"
            }
          }
        ]
      }
    }
  ]
}

data 필드를 base64에서 디코딩하면 이미지 파일이 됩니다. 비동기 경로는 이미지를 대신 저장해 주고 작업 객체에 호스팅된 url 을 반환하므로 base64 디코딩이 필요 없습니다.

에러 코드

오류는 0이 아닌 code 를 담은 표준 엔벨로프로 반환되며, 동기 엔드포인트의 경우 무료 생성에서 설명한 원본 오류 본문으로 반환됩니다.

두 생성 엔드포인트 모두 사용자별 및 전역 레이트 리밋이 적용됩니다. base64 참조 이미지(inlineData)를 담은 요청에는 별도의 더 엄격한 제한이 적용되며, 피크 시간대에는 가장 먼저 제한될 수 있습니다. estimate-credits 에는 레이트 리밋이 없습니다.

콘텐츠 검토

동기 오류 객체와 작업 상세·목록의 실패한 작업 객체에는 선택적 contentModeration이 포함될 수 있습니다. 검토에 따른 거부가 확인된 경우에만 반환됩니다. code, status, message를 포함한 기존 필드와 값은 바뀌지 않습니다. 기존 오류 처리에 이 메타데이터를 추가로 활용하세요.

사유가 비어 있거나 알 수 없으면 일반적인 검토 거부 안내를 표시하세요. 공급자의 원본 오류 문구 대신 짧게 현지화한 자체 문구를 사용하세요. 메타데이터 예시:

{
  "contentModeration": {
    "rejected": true,
    "reasons": [],
    "stage": "unknown"
  }
}

프롬프트나 참조 이미지 검토로 생성이 차단되면 contentModeration을 사용합니다. 생성은 성공했지만 공개할 수 없는 이미지에는 동일한 구조의 선택적 publicationModeration이 포함될 수 있습니다. stage는 실제 검토 대상을 유지하며, 프롬프트 제한은 input, 생성 이미지 제한은 output, 둘 다 제한의 원인이면 unknown입니다. 공개 제한은 생성 실패를 의미하지 않습니다. 기존 성공 상태와 이미지 URL은 유지되며, 보기와 다운로드에는 기존 접근 권한 규칙이 적용됩니다. “공개 불가”와 고정된 사유를 표시하고, 필드가 없으면 제한을 추정하지 마세요.

관련 문서