작성자 adsturbo.ai ｜ 게시일 2026-10-15 ｜ 수정일 2026-10-15
이커머스 광고 영상 생성 API 연동의 핵심은 생성 요청을 보내는 코드가 아니라, 상품 변경부터 결과 검수까지 추적하는 비동기 작업 체계다. ERP에서 상품을 저장할 때 영상 완성까지 기다리기보다, 제작 요청을 별도 작업으로 등록하고 완료 결과를 상품과 연결하도록 설계하자.
이 글은 특정 SDK의 호출 예제가 아닌, 대형 쇼핑몰의 상품관리 시스템에 적용할 수 있는 설계안이다. 특히 생성에는 성공했지만 가격이나 재고가 바뀌어 게시하면 안 되는 영상을 어떻게 구분할지 다룬다.
비동기 연동은 무엇이며 왜 필요한가?
비동기 연동은 요청 접수와 처리 완료를 분리하는 방식이다. 상품 저장은 먼저 끝내고, 영상 제작 결과는 작업 식별자로 나중에 확인한다.
Microsoft의 비동기 요청·응답 패턴은 오래 걸리는 처리를 백그라운드로 분리하고 상태 조회로 결과를 확인하는 구조를 설명한다. 요청을 받았다는 응답과 실제 작업 성공을 구분하는 것이 출발점이다. (learn.microsoft.com)
AdsTurbo의 생성 작업은 비동기로 실행되며, 상태 폴링 또는 웹훅 콜백으로 완료 이벤트를 받을 수 있다. 따라서 ERP 연동에서도 ‘요청 완료’를 곧바로 ‘영상 완성’으로 표시하지 않는 편이 맞다.
권장 책임 분리는 다음과 같다.
- ERP·상품관리 시스템: 상품 정보와 제작 필요 여부 관리
- 연동 서버: 입력 검증, 요청 전송, 작업 상태 정규화
- 작업 큐와 워커: 제출 속도, 재시도, 우선순위 제어
- 검수·게시 시스템: 결과 확인 후 배포 여부 결정
상품 등록 화면에는 제작 상태를 보여주되, 외부 생성 작업 때문에 상품 저장 자체를 되돌리는 구조는 피하자.
ERP에서 어떤 데이터를 전달해야 하는가?
영상 제작에는 상품 전체 데이터베이스보다 광고 표현에 필요한 최소 입력과 그 입력의 버전이 중요하다. 제작 당시 정보를 보존해야 나중에 결과의 유효성을 판단할 수 있다.
다음 표는 공급자 요청 명세가 아니라, 쇼핑몰 내부에 두도록 제안하는 작업 레코드다.
| 내부 관리 항목 | 저장 목적 |
|---|---|
| 상점·상품·옵션 식별자 | 결과를 정확한 판매 단위와 연결 |
| 상품 이미지 버전 | 변경 전 이미지로 만든 결과 식별 |
| 광고 문구·혜택 스냅샷 | 제작 당시 표현을 재현 |
| 언어·화면 비율·템플릿 버전 | 제작 변형 구분 |
| 내부 작업 ID·공급자 작업 ID | 양쪽 상태 추적 |
| 소재 권리 확인 상태 | 사용 승인된 입력만 제출 |
| 검수·게시 상태 | 생성 성공과 배포 승인 분리 |
주문자 이름, 배송지처럼 광고 제작에 필요 없는 데이터는 전달 대상에서 제외하는 설계를 권한다. 상품 이미지도 변경 가능한 파일 경로만 기록하기보다 버전이나 콘텐츠 해시를 함께 보관하자.
정지 이미지에서 어떤 장면을 만들지 결정하지 않았다면 누끼 이미지로 제품 영상을 구성하는 방법을 먼저 제작 명세에 반영할 수 있다. 화면 구성이 정리되어야 자동 생성 결과도 일관된 기준으로 검수할 수 있다.
작업 큐와 상태 전이는 어떻게 설계하는가?
내부 상태는 공급자 상태를 그대로 복제하지 말고, 쇼핑몰의 제작·검수·게시 흐름에 맞춰 정의하자. 특히 외부 제출 여부가 불확실한 상태를 별도로 관리하는 설계를 권한다.
권장 흐름은 ‘대기 → 제출 중 → 생성 중 → 생성 완료 → 검수 승인 → 게시’다. 여기에 제출 확인 필요, 재시도 대기, 검수 반려, 게시 보류를 추가한다.
- 상품 변경과 제작 요청 기록을 같은 데이터베이스 트랜잭션으로 저장한다.
- 별도 발행기가 미전송 요청을 큐에 전달한다.
- 워커가 입력을 확인하고 생성 API를 호출한다.
- 공급자 작업 ID를 저장한 뒤 완료 확인을 시작한다.
- 결과를 확보하면 검수 단계로 이동한다.
이 글에서 제안하는 첫 번째 통제점은 상품 변경과 제작 요청 기록의 원자성이다. 상품은 저장됐지만 요청이 사라지거나, 저장되지 않은 상품으로 제작되는 경우를 막는 목적이다.
한편 HTTP 202, 상태 조회 주소, 조회 간격 안내는 일반적인 비동기 설계 요소이지 모든 공급자의 동일한 응답 계약은 아니다. 실제 필드와 상태값은 해당 API 명세에 맞춰 매핑해야 한다. (learn.microsoft.com)
웹훅과 폴링은 어떻게 조합하는가?
이 글의 권장안은 웹훅을 주 경로로 사용하고, 오래 갱신되지 않은 작업만 폴링으로 대사하는 혼합형이다. 수신 서버 운영이 어렵다면 폴링부터 시작해도 된다.
| 방식 | 적합한 상황 | 내부 구현에서 점검할 부분 |
|---|---|---|
| 웹훅 | 완료 이벤트를 수신할 서버가 있는 경우 | 발신자 확인, 중복 처리, 저장 후 응답 |
| 폴링 | 외부 콜백 수신이 제한된 경우 | 조회 간격, 전체 대기 시간, 호출량 |
| 혼합형 | 미완료 작업의 누락 점검이 필요한 경우 | 두 경로가 같은 상태 전이 함수를 사용 |
폴링은 계속 같은 간격으로 모든 작업을 조회하기보다, 경과 시간과 공급자 안내에 맞춰 간격을 조절하도록 설계하자. Microsoft 문서 역시 상태 조회 위치와 재조회 간격을 전달하는 방식을 설명한다. (learn.microsoft.com)
웹훅 본문은 먼저 수신 기록에 보존하고 후속 처리를 분리하는 방안을 권한다. 발신자 검증은 공급자가 문서화한 인증 방식에 맞추되, 확인되지 않은 서명 헤더나 재전송 보장을 임의로 가정하면 안 된다.
재시도할 때 중복 생성을 어떻게 방지하는가?
재시도는 ‘실패했으니 다시 생성’이 아니라 기존 요청이 접수됐는지 확인한 뒤 판단하는 절차여야 한다. 응답 시간 초과만으로 생성 요청이 실패했다고 단정하지 말자.
내부 중복 방지 키는 상점, 상품 옵션, 소재 버전, 문구 버전, 언어, 화면 비율, 템플릿 버전을 조합해 만들도록 제안한다. 같은 조합의 작업이 존재하면 새 제출 대신 기존 작업을 조회한다.
다만 내부 중복 방지만으로 공급자 측 중복 실행까지 보장할 수는 없다. 공급자가 멱등성 키를 지원하는지 확인하고, 지원 여부가 불명확하면 응답 유실 작업을 자동 재제출하지 않고 ‘제출 확인 필요’로 격리하자.
오류도 구분해야 한다.
- 인증·필수 입력 오류: 수정 전까지 재시도 중단
- 일시적 통신 장애·호출 제한: 백오프와 지터 적용
- 접수 여부 불명: 기존 작업 확인 후 후속 판단
- 최대 대기 시간 초과: 운영자 확인 대상으로 이동
AWS는 재시도에서 멱등성을 확인하고, 지수 백오프·지터·최대 재시도 한도를 적용하도록 권고한다. (docs.aws.amazon.com)
대량 생성 물량과 처리 시간은 어떻게 계산하는가?
물량은 상품 수가 아니라 상품별 변형 수까지 곱해서 산정하자. 처리 시간도 평균 생성 시간 하나로 약속하지 말고, 동시 실행 한도와 검수 시간을 분리해야 한다.
다음은 실측 결과가 아닌, 용량 계획을 위한 가상 계산이다.
| 가정 | 계산값 |
|---|---|
| 대상 상품 400개 × 언어 2개 × 화면 비율 3개 | 2,400개 작업 |
| 작업당 평균 점유 시간 90초 가정 | 총 216,000작업초 |
| 실제 동시 실행 수 20개 가정 | 이론상 10,800초 |
| 초를 시간으로 환산 | 약 3시간 |
이 계산은 생성 단계가 일정하게 실행되고 추가 병목이 없다는 가정이다. 업로드, 공급자 대기열, 재시도, 다운로드, 검수 시간은 포함하지 않았다. 워커 20개를 실행한다고 공급자 작업 20개가 동시에 처리된다는 뜻도 아니다.
예산은 ‘기능별 출력 초수 × 해당 크레딧 요율’로 분리하고, 실행 중인 작업의 예상 사용량을 내부 예약 장부에 반영하는 방안을 권한다. 이 예약 장부는 공급자의 과금 기능이 아니라 쇼핑몰 측 통제 장치다.
대량 제작의 목적이 실험이라면 페이스북 광고 소재 변형과 테스트 전략에 맞춰 변형 축부터 줄이는 것이 좋다.
상품이 바뀌면 완성된 영상은 어떻게 처리하는가?
생성 완료와 게시 가능은 서로 다른 판단이다. 제작 중 가격·혜택·이미지가 바뀌었다면 결과를 무조건 폐기하기보다 무엇이 영상에 표현됐는지에 따라 재검수하도록 설계하자.
이 글의 핵심 제안은 ‘제작 잠금’과 ‘게시 잠금’을 분리하는 두 단계 유효성 관문이다.
| 관문 | 확인 시점 | 권장 판단 |
|---|---|---|
| 제작 잠금 | 생성 요청 직전 | 입력 버전과 소재 권리를 고정 |
| 게시 잠금 | 게시·재게시 직전 | 현재 상품 정보와 광고 표현 비교 |
예를 들어 재고가 0이 되었다면 새 광고 배포를 보류하되 결과 파일까지 삭제할 필요는 없다. 반면 영상에 할인 가격이 표시되었는데 행사 조건이 바뀌었다면, 해당 결과는 수정 또는 재제작 대상으로 분류한다.
변경마다 모든 영상을 다시 만들지 않도록 ‘영상에 포함된 표현’도 기록하자. 가격 미표시 영상은 가격 변경만으로 자동 폐기하지 않는 식이다.
다국어 소재에서는 숫자, 통화, 상품명 표기를 별도로 확인해야 한다. 글로벌 광고 자막 번역과 싱크 검수 기준을 승인 체크리스트에 연결하면 검수 항목을 구체화할 수 있다.
AdsTurbo 연동 범위는 어떻게 나누는가?
AdsTurbo는 Bearer API 키 인증을 사용하는 REST API와 비동기 작업 처리를 제공한다. 연동 서버는 인증과 작업 추적을 담당하고, ERP는 상품 정보의 기준 시스템으로 유지하도록 구성하자.
AdsTurbo API는 이미지 생성, 페르소나, AI 배우, 광고 복제, 영상 생성, 작업 처리의 여섯 가지 조합 가능한 모듈을 제공한다. 고급 요금제에는 팀 워크플로, API 접근, 맞춤형 워크플로 지원이 포함된다. 인증·비동기 처리·모듈 구성은 AdsTurbo 제공 기능 자료를 기준으로 한다.
기능상 광고 복제, 상품 영상, 번역, 자막 등으로 제작 단계를 나눌 수 있지만, 화면 기능과 API 요청 규격을 같은 것으로 가정해서는 안 된다. 실제 연동 전에는 입력 형식, 작업 조회 방식, 콜백 구성, 결과 다운로드 조건을 기술 지원팀과 확인하자.
첫 범위는 ‘한 상품 → 한 결과 → 상태 확인 → 검수’로 제한하는 것을 권한다. 이후 다국어와 다중 소재 변형을 추가하면 장애 원인을 분리하기 쉽다.
자주 묻는 질문
실제 운영 전에는 무엇을 시험해야 하나?
중복 완료 이벤트, 응답 유실, 지연 완료, 가격 변경, 결과 다운로드 실패의 다섯 가지 상황을 검증하도록 권한다. 이는 수행 결과가 아닌 인수 테스트 제안이며, 통과 기준은 각각 단일 상태 전이, 무조건 재제출 금지, 대사 가능, 게시 보류, 다운로드만 재시도다.
공급자 작업이 완료되면 바로 광고를 게시해도 되나?
권장하지 않는다. 내부 생성 완료 상태와 검수 승인 상태를 분리하고, 게시 직전에 상품·프로모션 유효성을 다시 확인하자. 광고 매체 등록은 생성 API 연동과 별도 작업으로 추적하는 편이 명확하다.
이미 완성된 파일의 다운로드만 실패하면 다시 생성해야 하나?
생성 완료가 확인됐다면 다운로드 단계만 재시도하도록 설계하자. 결과 파일의 보관 기간과 접근 URL 만료 조건을 확인하고, 확보한 결과는 승인된 내부 저장소로 이관하는 정책을 정한다.
운영 대시보드에는 어떤 지표가 필요한가?
대기 작업 수, 가장 오래 대기한 시간, 제출 확인 필요 건수, 완료까지의 지연, 검수 반려율, 게시 보류율을 권한다. 성공한 생성 수뿐 아니라 실제로 게시 가능한 소재 수를 함께 봐야 자동화의 유효성을 평가할 수 있다.
