이미지 편집 API: 참조 이미지 연동과 상품 이미지 검수

상품 이미지의 검수 조건부터 정한 뒤 참조 입력, 응답, 다운로드, 실패 처리를 설계합니다. 제공 자료로 확인할 수 없는 InkRoom 편집 API 요청이나 실행 결과는 만들지 않습니다.

2026-10-28 · 2026-10-28

이미지 편집 API(image editing api)를 연동할 때는 요청 성공만 확인해서는 안 됩니다. 어떤 원본을 보냈는지, 받은 파일을 사용할 수 있는지, 상품의 라벨·색상·윤곽이 유지됐는지까지 확인해야 합니다.

이 글은 연동 설계와 검수 가이드이며, 실행을 검증한 InkRoom API 튜토리얼이 아닙니다. 제공 자료에는 편집 엔드포인트, 인증 방식, 요청 필드, 응답 구조가 없습니다. 해당 명세가 확인되기 전에는 실행 가능한 호출 예제 작성을 보류해야 합니다. 아래 내용은 설계 제안이며, 실제 요청이나 결과 측정은 수행하지 않았습니다.

요청보다 검수 조건을 먼저 정하기

작업 관점에서 텍스트 기반 생성은 새 이미지를 말로 설명하는 방식입니다. 참조 이미지 편집은 기존 이미지도 입력하고, 바꿔도 되는 부분과 유지해야 할 부분을 정합니다. eesel의 이미지 편집 가이드도 이미지와 프롬프트를 편집 입력으로 설명하지만, 이것이 InkRoom의 요청 규격을 증명하지는 않습니다.

배경만 교체하는 작업이라면 다음과 같은 검수 조건부터 마련할 수 있습니다.

이는 검수 기준 제안이지 모델의 보존 성능 보장이 아닙니다. 프롬프트로 보존을 요청할 수는 있지만, 실제 보존 여부는 확인해야 합니다. 원본 라벨을 읽을 수 없다면 선명한 이미지나 승인된 문구를 확보하고, 모델이 추측하게 두지 않는 편이 좋습니다.

구현 전에 연동 명세 확인하기

최신 공식 문서에서 다음 사항을 확인합니다.

• 참조 이미지 편집 지원 여부, 입력 방식, 허용 형식·용량·이미지 수.
• 인증, 엔드포인트, 사용 가능한 모델과 필수 필드. 다른 공급자의 매개변수를 그대로 가져오지 않습니다.
• 응답이 이미지 데이터인지, 다운로드 주소인지, 작업 식별자인지. 비동기 방식이라면 완료와 실패를 어떻게 판정하는지.
• 다운로드 권한과 만료 조건, 오류 유형, 재시도 규칙, 중복 제출 처리 방식.

제공된 InkRoom 제품 정보만으로는 참조 이미지 편집 프로토콜이나 상태 조회, 다운로드 방식을 확인할 수 없습니다. 이 글에서는 확인되지 않은 요청 예제나 제품 기능을 제시하지 않습니다. 모르는 필드는 그럴듯한 값으로 채우지 말고 구현 차단 항목으로 남겨야 합니다.

애플리케이션 기록으로 처리 흐름 연결하기

다음과 같은 내부 상태를 설계할 수 있습니다.

입력 등록 → 제출 대기 → 제출 완료 → 파일 확보 → 검수 대기 → 승인 / 반려

이는 애플리케이션 내부 상태 제안이며 InkRoom이 반환하는 상태값이 아닙니다. 실제 명세가 비동기 방식일 때만 대기와 조회 단계를 추가합니다. 파일을 바로 반환하는 방식에 임의의 폴링 절차를 넣을 필요는 없습니다.

작업마다 사용 권한이 있는 원본, 편집 지시 버전, 내부 작업 식별자, 결과 파일 식별자를 연결해 두는 것이 좋습니다. 공급자가 요청 식별자를 실제로 반환한다면 문제 조사에 활용할 수 있습니다. 다만 로그에 비밀키나 민감한 이미지를 노출해서는 안 됩니다.

파일을 확보한 뒤에는 먼저 디코딩과 형식·크기·투명도 조건을 확인하고, 그다음 상품 내용을 검수합니다. 응답을 받았다는 사실을 곧바로 게시 승인으로 바꾸지 않습니다.

실패와 결과 불명을 구분하기

명확한 입력·권한 오류: 파일, 권한 또는 설정을 수정한 뒤 다시 제출합니다. 같은 요청을 무조건 반복하지 않습니다.

제출 후 시간 초과: 처리 결과가 불명확할 수 있습니다. 문서에 조회 방법이 있으면 기존 작업을 확인하고, 멱등성 기능도 명시된 경우에만 사용합니다. 확인 수단이 없다면 자동 중복 제출 대신 사람이 대조할 경로를 남깁니다.

다운로드 실패: 이미 생성된 결과가 있는지 먼저 확인합니다. 실제 명세에 따라 다시 가져오되, 곧바로 재생성을 시작하지 않습니다.

시각적 검수 실패: 반려 이유를 기록하고 결과를 게시 대상에서 제외합니다. 글자나 형태가 손상된 문제는 HTTP 재시도만으로 해결됐다고 판단할 수 없습니다. 입력이나 지시를 수정한 결과도 다시 검수해야 합니다.

상품 검수와 전달 확인을 따로 수행하기

원본과 결과에서 같은 상품 영역을 나란히 비교하고 라벨과 가장자리를 확대해서 확인합니다. 내보낸 파일 자체도 별도로 검사합니다. 색상은 일관된 보기 환경에서 비교하고, 색 관리 방식과 허용 오차가 없다면 완전히 같은 색이라고 단정하지 않습니다.

OCR은 문자 이상을 찾는 보조 수단으로 사용할 수 있지만, 라벨 정확성의 유일한 근거로 삼아서는 안 됩니다. 문자, 구조 또는 부속품에 의문이 있으면 상품을 잘 아는 담당자가 확인해야 합니다.

참고 가이드는 출력 검토와 다음 시스템 확인을 구분합니다. 상품 이미지에서도 승인한 파일이 실제 게시 대상에 전달됐는지 확인해야 합니다. 이전 버전이나 미검수 파일이 올라가지 않도록, 자동 게시 조건은 API 응답이 아니라 명시적인 검수 통과에 연결하는 것이 좋습니다.

다음 단계는 공식 편집 명세와 사용 권한이 있는 검수 이미지를 확보하는 일입니다. 그 이후에야 확인된 필드로 요청·응답·다운로드 예제를 작성하고, 실제 실행한 경우에만 실행 결과로 기록할 수 있습니다.