GloopAPI 연동 가이드
비동기 작업과 멱등성
작업을 복구하고 불명확한 제출을 처리합니다.
멱등성 키는 애플리케이션의 한 비즈니스 작업을 나타냅니다. 전송 전에 요청 본문, API 키 식별 정보와 요청 키를 영구 저장하세요. 재전송에는 동일한 키와 정규화된 입력을 사용해야 합니다. 같은 키로 요청을 변경하면 충돌하고, 다른 키를 사용하면 새로운 유료 작업이 생성됩니다.
견적과 생성
영구 보관 이미지와 동영상은 먼저 기능 카탈로그를 읽고, 입력을 업로드하거나 가져온 다음, 견적을 받고 생성을 명시적으로 확인합니다. 이미지와 동영상 견적의 유효 기간은 60초이고 도구 견적은 300초입니다. 실제 만료 시각은 서버의 expires_at입니다. 견적은 서비스에 요청을 제출하거나 요금을 발생시키지 않습니다. 아직 제출하지 않은 새 호출에서 견적이 만료되거나 입력/설정이 바뀌면 새 견적을 받고 생성 전에 새 비용을 확인하세요. 요청을 제출했지만 결과가 불명확하다면 원래 견적이나 요청을 수정하지 마세요.
이미지 견적은 입력 자산을 잠그지 않으며 생성 시 다시 검증합니다. 동영상은 현재 모드에 맞는 완전한 프리셋과 관리형 프레임만 허용합니다. 영구 보관 동영상은 retention: "persistent"를 명시적으로 제출하며 일반 동영상에는 별도의 URL 입력 계약이 계속 적용됩니다.
제출 결과가 불명확할 때의 판단
작업 ID를 받았다면 원래 작업만 조회하세요. ID를 받기 전에 요청 시간이 초과되면 영구 보관 이미지와 동영상의 복구 엔드포인트에 원래 요청 키를 사용하세요. 원래 작업 기록이 있으면 계속 관찰합니다. 상태가 unknown, submission_unknown, submission_state_unknown, billing_review 또는 검토 대기라면 실패나 환불로 간주하지 말고 다른 키로 다시 생성하지 마세요.
도구는 원래 API 키로 알려진 run_id를 조회합니다. 생성 응답을 잃어 run_id가 없다면 원래 API 키, 원래 Idempotency-Key와 원래의 전체 요청 본문으로 POST /v1/tool-runs를 재전송하고 원래 quote_id/version/input/max_cost_usd를 유지하세요. 접수된 실행은 새 견적이나 현재 기능 스위치에 의존하지 않고 원래 기록을 직접 복원하며 서비스에 다시 제출하지 않습니다. 기록은 created_at 내림차순, 이어서 id 내림차순으로 정렬됩니다. next_cursor는 변경 없이 전달해야 합니다. 페이지 나누기는 스냅샷이 아니므로 커서 앞에 정렬되는 새 기록은 첫 페이지를 새로 고쳐 확인하세요. 오디오 복제에는 동등한 요청 키 복구 엔드포인트가 없습니다. 제출 결과가 불명확하면 증거를 보존하고 조사하세요. 이미지 복구 경로를 적용하지 마세요.
세 가지 독립적인 상태
생성 성공, 요금 정산, 저장 준비 상태를 각각 판단하세요. 이미지는 일부만 성공할 수 있고 도구는 성공해도 최종 사용량이 확정되지 않을 수 있으며 동영상은 생성에 성공해도 저장에 실패할 수 있습니다. 백그라운드 작업자는 영구 보관 작업을 계속 처리하므로 브라우저를 닫거나 클라이언트 폴링을 중단해도 작업은 취소되지 않습니다.
취소는 요청일 뿐이며 지원되지 않거나 성공을 막기에는 늦을 수 있습니다. 최종 상태와 요금을 계속 확인하세요. 저장 재시도/archive-retry는 원래 결과만 저장하고 새 콘텐츠를 생성하지 않습니다. 작업 삭제에는 종료 상태와 확정된 정산이 필요하며 삭제 후에도 멱등성과 과금 증거는 남습니다.
결과를 조회한 뒤 저장 준비가 완료되었는지 확인하고 단기 파일 다운로드 URL을 요청하세요. 서비스 임시 URL이 만료되면 보관을 복구하지 못할 수 있습니다. 다시 생성하여 원래 작업의 저장 오류를 숨기지 마세요. 요금과 오류 처리를 참고하세요.