# API 요청이 타임아웃될 때 중복 영상 작업을 방지하는 방법은? > 각 의도된 출력에 안정적인 작업 키를 부여하고, 전송 전에 요청을 영구 저장하며, 가능한 경우 문서화된 공급자 멱등성을 사용하고, 모호한 타임아웃을 조정한 뒤 재시도하세요. 타임아웃은 공급자의 거부가 아니라 결과를 알 수 없다는 뜻입니다. # API 요청이 타임아웃될 때 중복 영상 작업을 방지하는 방법은? 제출 타임아웃은 모호한 결과를 만듭니다. 요청이 서비스에 도달하기 전에 실패했거나, 도달했지만 거부되었거나, 원격 영상 작업을 만들었지만 응답이 클라이언트로 돌아오지 않았을 수 있습니다. 즉시 재시도하면 한 개의 의도된 영상이 두 번 과금될 수 있습니다. 해결책은 영상 API 주변에 멱등 작업 계층을 두는 것입니다. 의도된 작업을 먼저 만들고 저장하며 안정적인 키를 부여하고 각 시도를 기록합니다. 문서화된 멱등성이나 조회 기능을 사용하고, 결과를 증명할 수 없으면 실패로 가정하지 말고 명시적인 알 수 없음 상태로 이동합니다. ## 하나의 의도된 부수 효과를 정의하세요 멱등 키는 개별 HTTP 시도가 아니라 사용자가 만들라고 한 결과를 식별해야 합니다. 재시도마다 새 키를 만들면 공급자는 중복을 알아볼 수 없습니다. 카탈로그 작업은 다음 요소로 정의할 수 있습니다. * 제품 ID * 크리에이티브 템플릿 버전 * 원본 미디어 지문 * 프롬프트 버전 * locale * 화면 비율 * 변형 이름 키 순서가 고정되고 값이 정규화된 표현을 만든 뒤 해시를 계산합니다. 읽기 쉬운 항목과 해시를 함께 저장하세요. 사용자가 별도의 새 생성을 의도했다면 프롬프트가 같아도 새 작업 또는 변형을 만듭니다. 재시도 루프 안에서 임의 UUID를 만들지 마세요. 첫 요청 전에 작업 키를 만들고 해당 부수 효과가 종료 상태가 될 때까지 재사용합니다. ## 전송 전에 영구 저장하세요 네트워크 호출 전에 로컬 DB가 작업을 알고 있어야 합니다. API 부수 효과에 적용하는 선행 쓰기 원칙입니다. | 필드 | 목적 | |---|---| | 작업 키 | 로컬 의도 중복 방지 | | 요청 해시 | 전송 파라미터 증명 | | 상태 | 준비, 전송, 알 수 없음, 완료 구분 | | 시도 횟수 | 제한된 재시도 정책 적용 | | 공급자와 모델 | 경로와 조정 지원 | | 원격 작업 ID | 재제출 없이 조회 재개 | | 최근 오류 | 진단 맥락 보존 | | 출력 체크섬 | 중복 또는 변경된 자산 탐지 | 작업 키에 고유 제약을 두세요. 두 worker가 같은 작업을 만들려 해도 한 레코드로 수렴해야 합니다. 전송 전에 원자적 업데이트나 lease로 가져옵니다. ## 문서화된 범위에서만 멱등성을 사용하세요 일부 API는 멱등 키를 받고 같은 키가 반복되면 최초로 수락한 결과를 반환합니다. 엔드포인트, 보존 기간, 파라미터 비교, 오류 동작이 명시될 때 가장 강력합니다. 다음을 확인하세요. * 영상 생성 엔드포인트가 키를 지원하는지 * 공급자가 얼마나 오래 기억하는지 * 같은 키와 다른 파라미터가 거부되는지 * 재시도가 원래 원격 ID를 반환하는지 결제나 동기 텍스트에서 지원하는 header가 비동기 영상에도 적용된다고 가정하지 마세요. OpenAI 호환 요청 형식만으로 작업 생성이 자동 멱등이 되지는 않습니다. ## 타임아웃을 알 수 없는 결과로 취급하세요 기대가 아니라 증거를 설명하는 상태를 사용합니다. | 상태 | 증거 | 다음 단계 | |---|---|---| | `prepared` | 로컬 기록 존재, 미전송 | 전송 | | `sending` | worker가 호출 시작 | 결과 또는 타임아웃 대기 | | `accepted` | 원격 ID 수신 | 조회 | | `unknown` | 확인 없이 타임아웃 | 조정 | | `failed` | 명시적 거부 또는 종료 실패 | 실패 정책 적용 | | `complete` | 출력 영구 저장 | 기존 결과 반환 | `unknown`과 `failed`의 차이가 중요합니다. 네트워크 예외는 클라이언트 연결의 증거이지 공급자 작업의 증거가 아닙니다. 클라이언트 참조나 메타데이터가 있으면 로컬 작업 키를 첨부해 이후 목록 조회나 지원 요청에서 찾을 수 있게 하세요. ## 재시도 전에 조정하세요 조정 worker가 알 수 없는 작업을 조사합니다. 1. 장애 전에 원격 ID가 저장되었는지 확인합니다. 2. 지원 시 멱등 키나 클라이언트 참조로 조회합니다. 3. 생성 시각, 모델, 요청 지문으로 제한된 작업 목록을 검색합니다. 4. 타임아웃 뒤 도착한 webhook을 확인합니다. 5. 충분히 빠르게 나오면 사용량이나 청구 이벤트를 비교합니다. 6. 작업이 없음을 증명하거나 멱등성으로 안전할 때만 재시도합니다. 시간과 프롬프트만으로 매칭하면 오탐이 생깁니다. 여러 속성을 사용하고 불확실하면 검토로 보냅니다. 조회도 멱등성도 없으면 대기, 중복 위험 수용, 비용과 기한에 따른 사람의 결정이 필요합니다. ## 전송 재시도와 생성 재시도를 분리하세요 HTTP 라이브러리는 네트워크 오류를 자동 재시도할 수 있습니다. 안전한 읽기에는 도움이 되지만 부수 효과가 있는 POST에는 위험합니다. 안정적인 키와 문서화된 지원이 없으면 비활성화하세요. 두 카운터를 사용합니다. * 같은 보호 작업을 보내는 전송 시도 * 종료 실패나 품질 거부 후 대체 출력을 만드는 생성 시도 전송 재시도는 같은 원격 작업으로 수렴해야 합니다. 생성 재시도는 새로운 과금 시도이며 원본 제작 작업에 연결된 별도 ID가 필요합니다. ## lease로 동시 worker를 제어하세요 타임아웃만 중복의 원인은 아닙니다. 두 worker가 같은 항목을 가져오거나 느린 worker가 lease 만료 후에도 계속할 수 있습니다. 소유자, 획득 시각, 만료를 가진 원자적 lease로 작업을 가져옵니다. 전송 전에 아직 소유하고 있고 기존 원격 작업이 없는지 확인합니다. 원격 ID는 다른 worker가 이미 진행했다면 실패하는 트랜잭션 또는 조건부 업데이트로 저장합니다. 오래된 worker가 쓸 수 있으면 fencing token을 사용합니다. lease 획득마다 버전을 올리고 DB는 최신 버전의 변경만 받습니다. ## webhook과 조회가 수렴하게 하세요 영상 작업은 비동기이므로 webhook과 조회가 같은 전환을 보고할 수 있습니다. 핸들러도 멱등이어야 합니다. 이벤트 ID로 중복 제거하고 `processing`이 `complete`를 뒤로 돌리지 못하게 조건부 업데이트를 사용합니다. 반복 다운로드는 결정적 임시 키에 쓰고 체크섬을 검증해 하나의 최종 객체로 수렴합니다. ```text 완료 이벤트 수신 원격 ID로 작업 조회 결정적 저장 키로 출력 복사 미디어와 체크섬 검증 영구 URI 기록 아직 완료가 아니면 완료 처리 ``` 어느 단계에서 중단되어도 다음 핸들러가 새 영상을 만들지 않고 재개할 수 있습니다. ## 중복 감사에 필요한 증거를 기록하세요 전송 전후 시각, 타임아웃 유형, 요청 해시, 멱등 키, 응답 header, 원격 ID, 재시도 결정을 보존하세요. 자격 증명과 민감 데이터는 마스킹합니다. | 지표 | 알 수 있는 내용 | |---|---| | 알 수 없는 제출 | 네트워크 또는 공급자 모호성 | | 재시도 없이 조정됨 | 방지된 중복 | | 보호된 재시도 | 장애 시 멱등 동작 | | 의심 중복 작업 | 남은 재무 위험 | | 중복 출력 체크섬 | 동일하거나 반복된 결과 | | 알 수 없음 상태 시간 | 복구 속도 | 알 수 없는 결과가 증가하면 재시도 한도를 늘리기 전에 원인을 조사하세요. 네트워크 악화와 공격적 재시도는 비용을 빠르게 키웁니다. ## 공급자 동작을 어댑터에 캡슐화하세요 다중 모델 앱은 공급자 기능 플래그가 있는 내부 제출 인터페이스를 제공해야 합니다. 어댑터가 엔드포인트 schema, 멱등성, 조회, 상태 매핑, 출력 추출을 담당합니다. [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=avoid-duplicate-video-jobs-api-timeout)는 하나의 OpenAI 호환 플랫폼에서 텍스트, 이미지, 영상을 사용하는 팀의 통합 작업을 줄일 수 있습니다. 그래도 정확한 모델과 엔드포인트의 현재 동작을 확인하세요. 호환성이 비동기 작업의 보편적 멱등성을 보장하지는 않습니다. 원격 ID와 함께 수락, 명시적 거부, 알 수 없음 같은 정규화 결과를 반환하세요. 전송 예외를 공급자 실패로 바꾸지 마세요. ## 모호한 상황을 의도적으로 시험하세요 사전 환경에서 전송 전, 바이트 전송 후, 공급자 수락 후, 응답 수신 후 DB 저장 전, webhook 전달 중에 장애를 주입하세요. 멱등성을 지원하면 하나의 의도된 작업이 최대 하나의 원격 작업을 만드는지 확인합니다. 지원하지 않으면 `unknown`으로 이동하고 자동 재제출을 멈추며 판단에 충분한 증거를 제공하는지 확인합니다. 동시 worker, 만료 lease, 지연 또는 중복 webhook, 재시작, 바뀐 파라미터와 기존 키 재사용도 시험하세요. 청구서에서 중복을 발견하는 것보다 저렴합니다. ## 결론 각 의도된 출력에 영구 작업 키를 부여하고 작업을 HTTP 시도와 분리하세요. 전송 전에 의도를 저장하고 문서화된 멱등성을 사용하며 타임아웃을 조정해야 하는 알 수 없는 결과로 취급하세요. lease, 조건부 상태 변경, 멱등 핸들러, 영구 로그를 사용하면 재시도는 우발적 중복 구매가 아니라 통제된 복구가 됩니다. ## FAQ ### HTTP 타임아웃은 영상 API가 작업을 만들지 않았다는 뜻인가요? 아닙니다. 클라이언트가 응답을 받지 못했어도 공급자가 요청을 수락하고 작업을 만들었을 수 있습니다. 조정이 끝날 때까지 결과를 알 수 없음으로 취급하세요. ### 멱등 키는 무엇을 나타내야 하나요? 제품, 템플릿 버전, locale, 화면 비율, 변형의 조합처럼 하나의 의도된 부수 효과를 나타내야 합니다. 같은 작업의 재시도에는 키를 재사용하고 실제 새 출력에는 새 키를 사용합니다. ### DB 고유 제약으로 모든 중복을 막을 수 있나요? 로컬 중복 작업은 막지만 공급자가 두 요청을 수락하는 것까지는 막지 못합니다. 공급자 멱등성 또는 조정 절차와 함께 사용하세요. ### 모든 타임아웃을 자동 재시도해야 하나요? 아닙니다. 요청이 멱등이거나 공급자 결과를 확인할 수 있을 때만 안전합니다. 그 외에는 알 수 없음 상태로 두고 먼저 조정하세요. ### 멱등 기록은 얼마나 오래 보관해야 하나요? 재시도 기간, 공급자 조회 기간, 청구 이의 기간, 감사 요구를 모두 포함할 만큼 보관하세요. 문서화된 동작과 사업 위험에 맞춥니다. ### OpenAI 호환 API는 모든 영상 모델에서 같은 멱등성을 보장하나요? 아닙니다. 전송 계층은 정규화할 수 있지만 비동기 작업 생성과 멱등성은 모델 또는 공급자별일 수 있습니다. 현재 엔드포인트 문서를 확인하세요.