WaveSpeedAI

Genjutsu API: 객체 교체 영상 한 편 제출하기

Genjutsu API로 객체 교체(Object Swap) 요청 한 건을 처리해 보세요. 원본 클립을 준비하고, 작업을 제출한 뒤, 편집된 영상을 받아오는 방법을 안내합니다.

By John5 min read
Genjutsu API: 객체 교체 영상 한 편 제출하기

Genjutsu API 통합에서는 영상 편집 작업이 ‘성공’으로 끝나도 팀이 쓸 수 없는 결과물이 남을 수 있습니다. 클립의 엉뚱한 구간이 처리되었거나, 교체된 객체가 프레임마다 흔들리거나, 아무도 출력물을 저장하지 않은 경우입니다. 그래서 저는 편집 한 건을 입력부터 승인된 파일까지 추적할 수 있게 만들 것을 권합니다. Higgsfield의 API quick start는 제출–폴링–조회 흐름을 설명하며, 이 가이드는 그 흐름을 Object Swap 요청 한 건에 적용합니다.

Higgsfield가 모델과 엔드포인트를 제공합니다. 제품에서 WaveSpeedAI를 사용한다면 모델 디렉터리에서 해당 작업을 지원하는지, 그리고 그 모델의 요청 스키마가 무엇인지 직접 확인하세요. 다른 영상 스왑 모델이 Higgsfield 요청을 그대로 받아들인다고 가정해서는 안 됩니다.

Genjutsu Object Swap 요청 한 건에는 무엇이 필요한가요?

요청 한 건에는 소스 영상 URL과 참조 이미지 URL 1~8개가 필요합니다. 프롬프트는 선택 사항입니다. resolution의 기본값은 720p이며, 480p와 1080p도 지원 목록에 있습니다. Object Swap API 레퍼런스는 이 모델을 higgsfield/genjutsu/object-swap/v1.0으로 명시합니다. 영상은 최소 4초 이상이어야 하며 프레임당 최소 409,600픽셀 이상이어야 합니다.

제출하기 전에 클립을 확인하세요. 30초보다 긴 영상은 30초로 잘리며, 출력도 그렇게 준비된 길이를 따릅니다. 의도한 편집이 34초 지점에 있다면, 요청이 성공하더라도 그 편집은 결과물에 담길 수 없습니다. 먼저 구간을 선택하고, 어떤 구간을 제출했는지 기록해 두세요.

서버 측 요청은 다음과 같은 형태가 될 수 있습니다. URL과 환경 변수는 예시입니다.

curl -X POST \
  "https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
  -H "Authorization: Key ${HF_KEY}" \
  -H "Idempotency-Key: ${EDIT_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/approved-source.mp4",
    "image_urls": ["https://example.com/approved-object.png"],
    "prompt": "Replace the featured cup with the reference cup.",
    "resolution": "720p"
  }'

자격 증명은 서버에만 보관하세요. 논리적으로 하나인 편집마다 고정된 멱등성 키를 부여하면, 제출 결과가 불분명할 때 의도치 않게 두 번째 작업을 만들지 않고 다시 시도할 수 있습니다. 소스에 식별 가능한 인물이 등장하거나 보호받는 영상·아트워크가 사용되었다면, 업로드하기 전에 필요한 권리와 동의를 확보하세요. 이는 운영 환경을 위한 알림이며 법률 자문이 아닙니다.

편집 제출과 상태 추적

POST가 성공했다는 것은 작업이 접수되었다는 뜻이지, 완성된 영상이 반환된다는 뜻이 아닙니다. 응답의 request_id, status_url, cancel_url을 제품의 편집 레코드에 함께 저장하세요. 이 URL들을 직접 만들어 쓰지 말고, 반환된 URL을 그대로 사용하세요.

Higgsfield의 요청 수명 주기 문서는 queued와 in_progress를 종료되지 않은 상태로 나열합니다. 상태가 completed, failed, nsfw, canceled 중 하나가 되면 대기를 멈추세요. 이 결과들은 UI에서 각각 구분해 보여 주세요. 제공업체가 이미 작업을 거부했는데 ‘아직 처리 중’이라고 표시하는 것은 좋지 않은 피드백입니다.

약 2초 간격으로 폴링을 시작하고, 대기 시간이 길어지면 간격을 늘리세요. 상태 확인 중 일시적인 네트워크 오류가 발생하면 상태 확인만 다시 시도하세요. 폴링 한 번이 실패했다고 해서 편집을 다시 POST하지 마세요. 최종 상태와 반환된 오류는 요청 ID와 함께 저장해 두세요. 그러면 지원팀이 생성 실패와 브라우저 세션이 일찍 끝난 경우를 구분할 수 있습니다.

완성된 영상 조회 및 확인

상태가 completed가 되면 결과에서 video.url을 읽습니다. 파일을 제품이 관리하는 스토리지로 다운로드한 뒤, 재생이 되는지, 의도한 편집과 일치하는지 확인하세요. API 작업이 완료되었다는 것은 전달 후보가 생겼다는 뜻일 뿐, 승인 결정이 아닙니다.

썸네일만 보고 끝내지 마세요. 클립의 시작, 중간, 끝에서 교체된 객체를 확인하고, 특히 객체가 다른 피사체 뒤로 이동하거나 프레임을 가로지르는 구간을 살펴보세요. 처리된 길이를 제출한 구간과 비교하세요. 소리가 기능에서 중요하다면 출력의 오디오 트랙도 점검하세요. Object Swap 레퍼런스는 소스 오디오 유지를 보장하지 않습니다.

출력 하나가 좋았다고 해서 운영 워크플로가 준비된 것은 아닙니다. 제공업체의 완료 상태는 파일이 존재한다는 사실만 알려 줍니다. 그 파일을 제품에 넣어도 되는지는 여러분의 승인 검사가 결정합니다.

운영 환경에서 Object Swap을 재현 가능하게 만들기

재실행 가능한 편집 매니페스트 저장

소스 에셋 버전, 선택한 시간 구간, 참조 이미지 버전, 프롬프트, 해상도, 모델 ID, 멱등성 키, 요청 ID, 최종 상태를 함께 보관하세요. 여기에 승인된 출력의 저장 위치를 추가하세요. 한 사람은 파라미터를 기억할 수 있지만, 팀은 그럴 수 없습니다.

이 기록은 편집자가 ‘같은 스왑인데 파란색 제품으로’를 요청할 때 도움이 됩니다. 팀은 final-v3.mp4라는 파일에서 이전 요청을 억지로 복원하는 대신, 입력 하나만 의도적으로 바꿀 수 있습니다.

원본과 승인된 출력 보관

롤백을 위해 원본 클립을 보관하고, 승인된 결과는 제공업체의 임시 미디어 위치 밖에 저장하세요. Higgsfield의 보존 및 동의에 관한 API 약관에 따르면 생성된 미디어는 최소 7일간 이용할 수 있지만 그 이후에는 삭제될 수 있습니다. 이는 영구 URL을 보장한다는 뜻이 아닙니다. 결과가 승인되었는지, 거부되었는지, 수정 요청과 함께 반려되었는지, 그리고 그 이유를 기록하세요.

FAQ

Object Swap은 소스 클립의 오디오를 유지하나요?

공개된 Object Swap 레퍼런스에는 이에 대한 언급이 없습니다. 제품에서 오디오 패스스루를 약속하지 마세요. 알아볼 수 있는 오디오 트랙이 담긴, 사용 권한이 있는 클립으로 테스트하고, 그 기능을 내세우기 전에 반환된 파일을 점검하세요.

대기열에 있는 Genjutsu 요청을 취소할 수 있나요?

네, 대기열에서 아직 취소 가능한 동안에는 가능합니다. 반환된 cancel_url로 취소 요청을 보내세요. 폴러를 멈추는 것만으로는 작업이 취소되지 않습니다. 문서화된 수명 주기에 따르면, 처리가 시작된 후에는 취소할 수 없습니다.

준비 중에 소스 URL이 만료되면 어떻게 되나요?

만료되는 Object Swap 입력 URL에 대해 모든 경우에 적용되는 단일한 실패 시점은 문서에 명시되어 있지 않습니다. Higgsfield가 가져와야 할 수 있는 동안에는 소스를 접근 가능한 상태로 유지하세요. 준비 단계가 실패하면 실제 요청 상태와 오류를 로그에 남기세요. POST가 접수되었다고 해서 파일이 이미 다운로드되었다는 것이 증명되지는 않습니다.

입력 준비 실패는 과금 단위를 소비하나요?

보고된 실패 유형에 따라 다릅니다. Higgsfield의 과금 및 보존 안내에 따르면 failed 또는 nsfw로 끝난 요청은 과금되지 않으며 예약된 크레딧은 환불됩니다. ‘입력 준비 실패’는 그 자체로 과금 상태가 아니므로, 그런 오류에 모두 같은 규칙을 적용하지 말고 응답과 과금 기록을 확인하세요.

완성된 영상 URL은 얼마 동안 유지되나요?

생성된 미디어는 최소 7일간 접근할 수 있으며 그 이후에는 제거될 수 있습니다. 승인된 영상은 바로 다운로드하세요. 사용자가 몇 주 뒤에 다시 찾아볼 수 있는 Genjutsu API 기능이라면, 저장해 둔 사본을 자체 스토리지에서 제공하세요.


이전 글:

공유