본문으로 건너뛰기

Image Generations

프롬프트를 바탕으로 새 이미지를 생성하세요.

OpenAI Images 호환 요청, 생성 옵션, base64 응답 저장과 오류 대응을 다룹니다.

POSThttps://gw.letsur.ai/v1/images/generations
AUTHAuthorization: Bearer <API_KEY>

지원 범위와 운영 방식

현재 이미지 생성은 gpt-image-2를 지원하며 AI 게이트웨이를 사용하는 모든 스페이스에 기본 제공됩니다. 별도 모델 배급 요청이나 OpenAI API 키는 필요하지 않습니다.

기존 AI 게이트웨이 API 키와 OpenAI 호환 클라이언트를 사용합니다. 요청에는 다른 게이트웨이 호출과 같은 인증 및 월 한도가 적용되고, 비용과 사용량도 같은 운영 화면에서 확인합니다. 지원 모델이나 옵션이 추가되면 에셋의 현재 정보를 기준으로 선택합니다.

요청 필드

요청 본문은 application/json으로 보냅니다.

필드타입요구 여부설명
modelstring필수gpt-image-2
promptstring필수생성할 이미지를 설명하는 프롬프트
sizestring선택모델이 지원하는 출력 크기
qualitystring선택모델이 지원하는 품질 옵션
ninteger선택생성할 이미지 수
backgroundstring선택모델이 지원하는 배경 옵션

선택 필드의 허용 값은 모델에 따라 달라질 수 있습니다. 현재 지원 범위는 에셋과 응답의 오류 내용을 기준으로 확인합니다.

응답 (200)

생성된 이미지는 응답의 data[].b64_json에 base64 문자열로 들어옵니다.

{
  "created": 1786723200,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ],
  "estimated_cost": {
    "amount": "0.04000000",
    "currency": "unit",
    "disclaimer": "Estimated based on published pricing. Actual charges may differ."
  }
}

클라이언트는 base64 문자열을 디코딩해 파일이나 객체 저장소에 보관합니다. 응답 문자열 전체를 일반 애플리케이션 로그에 남기지 마세요.

estimated_cost는 이 이미지 생성 호출의 비용입니다. 영상이나 작업별로 비용을 묶으려면 응답의 amount와 currency를 고객 시스템의 작업 식별자와 함께 저장합니다. 자세한 의미는 요청별 비용을 확인합니다.

요청과 결과 저장 예시

아래 예제는 셸 또는 서버 환경에 설정된 LETSUR_API_KEY를 읽습니다. 키 설정과 첫 실행은 첫 API 호출에서 확인합니다.

(
  test -n "${LETSUR_API_KEY:-}" || { echo "LETSUR_API_KEY가 필요합니다." >&2; exit 1; }
  env -u LETSUR_API_KEY curl https://gw.letsur.ai/v1/images/generations \
    --header @- \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "푸른 하늘 아래 달리는 자동차",
      "size": "1024x1024",
      "n": 1
    }' <<EOF
Authorization: Bearer ${LETSUR_API_KEY}
EOF
)

제약과 오류

  • 이 엔드포인트는 스트리밍을 지원하지 않습니다. stream: true를 보내지 않습니다.
  • 이미지 생성이 오래 걸릴 수 있으므로 클라이언트의 요청 제한 시간을 충분히 둡니다.
  • invalid_model (400)이면 모델은 존재하지만 이 엔드포인트에서 지원하지 않는 모델입니다. gpt-image-2를 사용했는지 확인합니다.
  • model_not_found (404)이면 현재 카탈로그에 없는 모델 코드입니다. 에셋에서 코드를 다시 확인합니다.
  • 인증, IP 제한, 유닛과 한도 오류는 오류 처리에서 확인합니다.
마지막 업데이트