Image Edits
입력 이미지의 일부 또는 전체 편집하기
multipart/form-data로 입력 이미지와 선택적 mask를 보내는 요청 형식, 응답 본문의 base64 결과와 비용 필드, 결과 저장 예제와 오류 대응을 설명합니다.
페이지 목차
https://gw.letsur.ai/v1/images/editsAuthorization: Bearer <API_KEY>지원 모델
이 엔드포인트는 입력 이미지와 프롬프트를 multipart/form-data로 받아 이미지를 편집합니다. OpenAI Images API와 같은 형식으로 응답하며, 편집된 이미지가 응답 본문에 base64 문자열로 들어 있습니다. 결과를 응답으로 바로 받는 동기 호출만 지원하며, 작업 ID를 반환하지 않으므로 같은 결과를 다시 조회할 수 없습니다.
| 모델 | 결과를 받는 방법 | 작업 조회와 비동기 요청 | 모델별 요청 필드와 입력 조건 |
|---|---|---|---|
GPT Image 2 (gpt-image-2) | 응답 본문의 data[].b64_json | 지원하지 않음 | GPT Image 2 가이드 |
이 엔드포인트를 쓰지 않고 Image Generations에 참조 이미지를 지정해 편집하는 모델도 있습니다. 모델마다 어느 엔드포인트를 쓰는지는 이미지와 영상 만들기의 모델별 호출 경로에서 확인합니다. 현재 스페이스에서 쓸 수 있는 모델과 입력 조건은 에셋에서 확인합니다.
요청에는 다른 게이트웨이 호출과 같은 인증 및 월 한도가 적용됩니다. 비용과 사용량도 다른 호출과 같은 운영 화면에서 확인합니다.
요청 필드
요청 본문은 multipart/form-data로 보냅니다. 여러 이미지를 보낼 때는 파일마다 같은 이름의 image 파트를 추가합니다. multipart boundary가 포함된 Content-Type 헤더는 직접 지정하지 않고 HTTP 클라이언트가 생성하게 합니다.
| 필드 | 타입 | 요구 여부 | 설명 |
|---|---|---|---|
model | string | 필수 | 호출할 모델 코드 |
prompt | string | 필수 | 입력 이미지의 편집 내용을 설명하는 프롬프트 |
image | file 또는 file[] | 필수 | 편집할 이미지 |
mask | file | 선택 | 편집할 영역을 안내하는 이미지 |
파일 형식, 개수와 크기, mask의 조건과 size, quality, n 같은 출력 옵션의 허용 값은 모델마다 다릅니다. 지원 모델 표에서 연결한 모델 가이드를 확인하세요.
mask를 보내려면 아래 cURL 예제에 -F "mask=@mask.png"를 추가합니다. mask 파일의 조건은 모델 가이드에 있습니다.
응답 (200)
다음은 설명용 응답이며 예시 모델은 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_json | string | 편집된 이미지의 base64 문자열 |
estimated_cost.amount | string(소수) | 이 이미지 편집 호출의 비용 |
estimated_cost.currency | string | 비용의 단위. 지금은 unit |
estimated_cost.disclaimer | string | amount가 공개 단가 기준이며 실제 청구액과 다를 수 있다는 안내 문구 |
base64 문자열은 디코딩해 파일이나 객체 저장소에 보관하세요. 응답 문자열 전체를 일반 애플리케이션 로그에 남기지 마세요.
작업별로 비용을 집계하려면 estimated_cost.amount와 estimated_cost.currency를 고객 시스템의 작업 식별자와 함께 저장합니다. 필드의 자세한 의미는 요청별 비용에 있습니다.
요청 예시와 결과 저장
아래 예제는 예시 모델 gpt-image-2로 현재 디렉터리의 input.png를 편집합니다. 예제는 셸 또는 서버 환경에 설정된 LETSUR_API_KEY를 사용합니다. 키를 설정하는 방법은 첫 API 호출에서 확인합니다.
cURL 예제를 실행한 뒤에는 JSON 응답을 확인합니다. Python 예제는 반환된 base64를 디코딩해 파일로 저장합니다.
SDK 예제는 자동 재시도를 끕니다. timeout이 나거나 응답을 받지 못한 뒤 같은 요청을 다시 보내기 전에 제약과 오류의 비용 안내를 확인하세요.
cURL
curl https://gw.letsur.ai/v1/images/edits \
-H "Authorization: Bearer $LETSUR_API_KEY" \
-F "model=gpt-image-2" \
-F "prompt=배경을 푸른 하늘로 바꿔줘" \
-F "image=@input.png"Python 예제로 저장한 파일을 열어 편집 결과를 확인하세요. 같은 이름의 파일이 있으면 Python 예제는 덮어쓰지 않고 중단합니다. 다시 실행하려면 다른 출력 경로를 지정합니다.
제약과 오류
동기 호출에서 timeout이 나거나 응답을 받지 못한 뒤 같은 요청을 다시 보내면 별도 호출로 처리됩니다. 원래 호출을 확인할지 새로 호출할지는 동기 호출의 재시도와 비용 확인에 따라 구분하세요.
이 엔드포인트는 스트리밍을 지원하지 않습니다. multipart/form-data 요청에 stream=true를 보내지 마세요.
인증, IP 제한, 유닛과 한도 오류는 오류 처리에 있습니다.