본문으로 건너뛰기

Image Generations

프롬프트로 이미지를 생성하고 결과 받기

모든 모델에 필수인 요청 필드, 모델에 따라 달라지는 두 가지 응답 형식, 비동기 요청과 웹훅 알림, 오류와 작업 실패 사유를 설명합니다.

페이지 목차
POST
https://gw.letsur.ai/v1/images/generations
인증Authorization: Bearer <API_KEY>

지원 모델

이 엔드포인트는 프롬프트로 새 이미지를 만듭니다. 모델에 따라 참조 이미지를 함께 보내 편집할 수도 있습니다. 결과를 돌려주는 방법은 요청의 model이 가리키는 모델에 따라 둘 중 하나입니다.

  • 결과를 응답 본문으로 받는 모델: OpenAI Images API와 같은 형식으로 응답하며, 생성된 이미지가 응답 본문에 base64 문자열로 들어 있습니다.
  • 작업 ID를 반환하는 모델: 응답에 렛서 작업 ID id와 이미지 URL이 들어 있습니다. 같은 id로 Jobs에서 결과를 다시 조회할 수 있고, 결과를 기다리지 않는 비동기 요청과 웹훅 알림을 쓸 수 있습니다.
모델결과를 받는 방법작업 조회와 비동기 요청모델별 요청 필드
GPT Image 2 (gpt-image-2)응답 본문의 data[].b64_json지원하지 않음GPT Image 2 가이드
Seedream 5.5응답의 data[].url과 작업 ID id지원Seedream 5.5 가이드

이 엔드포인트를 쓰지 않는 이미지 모델도 있습니다. 모델마다 어느 엔드포인트를 쓰는지는 이미지와 영상 만들기의 모델별 호출 경로에서 확인합니다. 현재 스페이스에서 쓸 수 있는 모델과 단가는 에셋에서 확인합니다.

요청에는 다른 게이트웨이 호출과 같은 인증 및 월 한도가 적용됩니다. 비용과 사용량도 다른 호출과 같은 운영 화면에서 확인합니다.

요청 필드

요청 본문은 application/json으로 보냅니다. 다음 두 필드는 모든 지원 모델에서 필수입니다.

필드타입요구 여부설명
modelstring필수호출할 모델 코드
promptstring필수생성하거나 편집할 이미지를 설명하는 프롬프트

그 밖의 필드는 모델마다 지원 여부와 허용 값이 다릅니다. size, n, background처럼 이름이 같은 필드도 모델마다 허용 값이 다르므로, 한 모델의 본문을 다른 모델에 그대로 보내지 마세요. 모델이 받는 필드와 허용 값은 지원 모델 표에서 연결한 모델 가이드에 있습니다.

요청 헤더와 쿼리 파라미터

작업 ID를 반환하는 모델에는 다음 헤더와 쿼리 파라미터를 함께 보낼 수 있습니다.

이름위치설명
Prefer: respond-async요청 헤더결과를 기다리지 않고 작업 ID를 먼저 받는 비동기 요청. 보내지 않으면 동기로 처리해 결과를 응답으로 반환. 비동기 접수 응답 참고
letsur_webhook쿼리 파라미터비동기 요청의 작업이 끝났을 때 알림을 받을 HTTPS 주소. URL 인코딩해서 넣음. 2,048자 이하. 웹훅 알림 참고

응답 (200)

응답 형식은 모델에 따라 두 가지입니다. 어느 모델이 어느 형식으로 응답하는지는 지원 모델 표에 있습니다.

base64 이미지 응답

OpenAI Images API와 같은 형식입니다. 다음은 설명용 응답이며 예시 모델은 gpt-image-2입니다.

{ "created": 1786723200, "data": [ { "b64_json": "iVBORw0KGgo..." } ], "estimated_cost": { "amount": "0.04000000", "currency": "unit", "disclaimer": "Estimated based on published pricing. Actual charges may differ." } }
필드타입설명
data[].b64_jsonstring생성된 이미지의 base64 문자열
estimated_cost.amountstring(소수)이 이미지 생성 호출의 비용
estimated_cost.currencystring비용의 단위. 지금은 unit
estimated_cost.disclaimerstringamount가 공개 단가 기준이며 실제 청구액과 다를 수 있다는 안내 문구

base64 문자열은 디코딩해 파일이나 객체 저장소에 보관하세요. 응답 문자열 전체를 일반 애플리케이션 로그에 남기지 마세요. 이 응답에는 작업 ID가 없으므로 같은 결과를 다시 조회할 수 없습니다.

고객 시스템에서 작업별로 비용을 집계하려면 estimated_cost.amount와 estimated_cost.currency를 그 작업의 식별자와 함께 저장합니다. 필드의 자세한 의미는 요청별 비용에 있습니다.

이미지 URL과 작업 ID 응답

Prefer: respond-async 헤더 없이 보내면 생성이 끝난 뒤 HTTP 200 응답으로 결과를 받습니다. 응답 본문은 모델 공급사의 응답 형식을 따르고, 맨 앞에 렛서 작업 ID id가 붙습니다. 작업 객체가 아니라 결과 본문입니다. 다음은 설명용 응답이며 예시 모델은 Seedream 5.5입니다. ID와 URL은 예시 값입니다.

{ "id": "lst-example-image-job-id", "model": "seedream-5.5", "created": 1794212764, "data": [ { "url": "https://gw.letsur.ai/v1/media/example-media-id?exp=...&sig=...", "size": "1248x832" } ], "estimated_cost": null }
필드타입설명
idstring렛서 작업 ID. 같은 결과를 Jobs의 GET /v1/jobs/{id}로 다시 조회할 때 씀
modelstring요청한 모델 코드
data[].urlstring결과 이미지의 URL. 렛서가 발급한 서명 URL이거나 모델 공급사가 준 URL일 수 있음
estimated_costnull예상 비용을 응답에서 제공하지 않는다는 뜻이며 무료라는 뜻이 아님. 비용은 Jobs의 data.job.usage에서 확인

그 밖의 필드는 모델마다 다르며 모델 가이드에 있습니다.

data[].url을 받았다고 해서 렛서가 결과 파일 보관을 마친 것은 아닙니다. URL로 받지 못했거나 링크가 만료됐을 때 같은 id로 Jobs를 조회해 다시 받는 순서는 생성 요청하고 결과 파일 받기의 이미지 결과 받기에 있습니다.

비동기 접수 응답

작업 ID를 반환하는 모델에 Prefer: respond-async 헤더를 보내면, 생성 결과를 기다리지 않고 HTTP 200 응답으로 작업 ID를 먼저 받습니다.

{"id": "lst-example-image-job-id", "estimated_cost": null}

응답 헤더 Preference-Applied: respond-async로 비동기 접수를 확인합니다. 이 헤더가 없으면 요청이 동기로 처리된 것이므로 응답 본문에서 결과를 확인합니다. cURL에서 응답 헤더를 보려면 -i를 추가합니다.

HTTP 200 접수 응답은 생성이 끝났다는 뜻이 아닙니다. 결과는 같은 id로 Jobs에서 조회합니다.

웹훅 알림

비동기로 요청할 때 요청 URL의 letsur_webhook 쿼리 파라미터에 HTTPS 주소를 넣으면, 작업이 끝났을 때 게이트웨이가 그 주소로 알림을 보냅니다. 주소는 URL 인코딩해서 넣습니다.

  • 주소 길이: 수신 주소는 2,048자 이하여야 합니다. 이 길이를 넘으면 요청은 웹훅 없이 접수됩니다.
  • 동기 요청: letsur_webhook을 넣어도 요청은 거절되지 않습니다. 동기 요청의 결과는 응답으로 받으므로 알림을 기다리지 마세요.

게이트웨이는 알림을 수신 주소에 POST 요청으로 보냅니다. 본문은 다음 형태입니다.

{"type": "job.succeeded", "data": {"job": {"id": "lst-example-image-job-id", "status": "succeeded"}}}

이 본문은 일부 필드만 표시한 예시입니다.

항목설명
type성공 알림은 job.succeeded, 실패 알림은 job.failed
data.job.id렛서 작업 ID
data.job.status작업 상태
webhook-id 헤더작업 ID와 같은 값. 다시 보낸 알림에도 같은 값이 들어감

알림에는 결과 파일의 정보가 없습니다. 알림을 받아 결과를 확인하고 중복 알림을 거르는 순서는 생성 요청하고 결과 파일 받기의 웹훅으로 완료 알림 받기에 있습니다.

요청 예시와 결과 저장

아래 예제의 예시 모델은 결과를 응답 본문으로 받는 gpt-image-2입니다. 예제는 셸 또는 서버 환경에 설정된 LETSUR_API_KEY를 읽습니다. 키를 설정하고 처음 실행하는 방법은 첫 API 호출에서 확인합니다.

cURL 예제를 실행한 뒤에는 JSON 응답을 확인합니다. Python 예제는 반환된 base64를 디코딩해 파일로 저장합니다.

SDK 예제는 자동 재시도를 끕니다. timeout이 나거나 응답을 받지 못한 뒤 같은 요청을 다시 보내기 전에 제약과 오류의 비용 안내를 확인하세요.

cURL
curl https://gw.letsur.ai/v1/images/generations \ -H "Authorization: Bearer $LETSUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "푸른 하늘 아래 달리는 자동차", "size": "1024x1024", "n": 1 }'

Python 예제로 저장한 파일을 열어 생성 결과를 확인하세요. 같은 이름의 파일이 있으면 Python 예제는 덮어쓰지 않고 중단합니다. 다시 실행하려면 다른 출력 경로를 지정합니다.

작업 ID를 반환하는 모델의 요청 예시는 각 모델 가이드에 있습니다. 결과 URL로 파일을 받는 순서는 생성 요청하고 결과 파일 받기의 이미지 결과 받기에 있습니다.

제약과 오류

응답을 받지 못한 요청을 다시 보내면 추가 비용이 생길 수 있습니다

동기 호출에서 timeout이 나거나 응답을 받지 못한 뒤 같은 요청을 다시 보내면 별도 호출로 처리됩니다. 원래 호출을 확인할지 새로 호출할지는 동기 호출의 재시도와 비용 확인에 따라 구분하세요. 작업 ID를 받았다면 새 생성 요청을 보내기 전에 그 작업부터 조회하세요.

  • 이 엔드포인트는 스트리밍을 지원하지 않습니다. stream: true를 보내지 마세요.
  • 이미지 생성은 오래 걸릴 수 있으므로 클라이언트의 요청 제한 시간을 충분히 길게 잡으세요.
  • 작업 ID를 반환하는 모델에서 게이트웨이가 모델 공급사에 요청을 보낸 뒤 결과를 확인하지 못하면, 게이트웨이는 같은 요청을 다시 보내지 않습니다. 동기 요청은 작업을 남기지 않고 오류로 응답하며, 그 요청에는 사용량을 기록하거나 유닛을 차감하지 않습니다. 비동기로 접수한 작업은 렛서가 결과를 기다리는 기간이 지난 뒤 dispatch_timeout으로 실패하고, 이때도 사용량을 기록하거나 유닛을 차감하지 않습니다.
오류원인과 할 일
invalid_model (400)지정한 모델은 있지만 이 엔드포인트에서 지원하지 않습니다. 선택한 모델의 지원 API와 그 모델의 가이드를 확인합니다
model_not_found (404)지정한 모델 코드가 에셋 목록에 없습니다. 에셋에서 코드를 다시 확인합니다

인증, IP 제한, 유닛과 한도 오류는 오류 처리에 있습니다. 모델마다 다른 거절 조건은 각 모델 가이드의 문제 해결에 있습니다.

작업 ID를 반환하는 모델의 오류

다음 오류는 error.code와 error.message로 반환됩니다.

HTTP코드뜻다음 행동
400validation_error필드나 값, 헤더가 모델의 조건에 맞지 않거나 모델 공급사가 요청을 거절함모델 가이드의 요청 필드와 허용 값을 확인. 공급사 거절이면 프롬프트나 참조 이미지를 수정
429queue_full작업 대기열 전체나 스페이스의 대기 작업 수, 또는 처리 한도에 도달해 새 요청을 받지 않음. 이미 접수한 작업은 영향을 받지 않음응답 헤더 Retry-After의 초만큼 기다린 뒤 다시 보냄. 다시 보내도 성공이 보장되지 않으므로 반복되면 간격을 늘림
502, 504UPSTREAM_ERROR, UPSTREAM_TIMEOUT게이트웨이가 모델 공급사의 결과를 받지 못함. 이 요청은 작업으로 남지 않고, 게이트웨이는 다시 보내지 않으며 사용량을 기록하거나 유닛을 차감하지 않음오류 상세를 확인한 뒤 새로 요청할지 판단
503QUEUE_UNAVAILABLE작업을 접수하거나 저장하지 못함잠시 뒤 다시 보냄
500-처리 중 오류응답 헤더의 요청 ID와 함께 문의

작업 실패 사유

Jobs의 data.job.status가 failed이면 data.job.error.type으로 원인을 구분합니다.

작업 오류뜻다음 행동
urn:letsur:error:vendor_rejected콘텐츠 심사를 포함한 모델 공급사의 거절프롬프트나 이미지를 수정
urn:letsur:error:dispatch_timeout공급사에 보낸 요청의 결과를 확인하지 못했고, 렛서가 결과를 기다리는 기간도 지나 실패로 끝남. error.title이 전달되지 않았다는 뜻으로 보여도 전송 뒤 결과를 확인하지 못한 경우를 포함함. 게이트웨이는 다시 보내지 않고 이 작업에 유닛을 차감하지 않음새로 요청할지 판단
urn:letsur:error:dispatch_attempts_exhausted여러 차례 공급사 전달에 실패함잠시 뒤 새 요청
urn:letsur:error:queue_expired접수 후 30분 안에 처리를 시작하지 못해 만료됨잠시 뒤 새 요청