증거 경계
비공개 인프라 다이어그램이 아닌 공공 계약 참조
소유권, 검증, 작업 상태, 재시도, 정산, 전달, 삭제 및 증거가 자체 통합에서 어디에 있어야 하는지 결정하는 데 사용하세요. 정확한 다중 부분 필드 및 응답을 위해 API 문서 및 OpenAPI 3.1 계약을 사용하세요.얼굴 위치 파악, 신원 전환, 합성, 블렌딩, 비디오 일관성에 대한 연구 개념을 위해, AI 얼굴 교체 작동 방식을 읽어보세요.
검증된 공개 계약
다섯 개의 비동기 워크플로우가 하나의 제어 형태를 공유합니다
모든 현재 세대 워크플로우는 Bearer API 키로 인증하고, 멀티파트 미디어를 수락하며, 다음을 반환합니다 taskId, 동일한 경로에서 GET을 통해 소유자 범위 상태를 노출합니다. 완료는 폴링을 사용합니다. 웹훅 콜백 및 공식 언어 SDK는 현재 게시되지 않았습니다.
| 워크플로우 | POST 및 폴링 GET | 비용 단위 | 기본 바운드 |
|---|---|---|---|
| 사진 | /api/ai-tasks | 작업당 3 크레딧 | 이미지당 30MB |
| 배치 사진 | /api/ai-tasks/batch-face-swap | 출력당 3 크레딧 | 20개 이미지, 95MB 결합 |
| 매핑된 단체 사진 | /api/ai-tasks/multi-face-swap | 대체 얼굴당 3 크레딧 | 10개 매핑된 얼굴, 95MB 결합 |
| 비디오 | /api/ai-tasks/video | 장면 보존이 있는 얼굴 전용: 1/s, 최소 5 at 1080p | 600초, 95MB 결합 업로드 |
| GIF / 짧은 클립 | /api/ai-tasks/gif | 초당 1 크레딧, 최소 5 | 30초, 95MB 대상 |
실시간 작업 공간과 API 문서는 정확한 형식, 최소 요금 및 요청 필드에 대해 권위를 가집니다. 인증된 계정 이메일이 필요하며, 계정당 하나의 생성이 활성화될 수 있고, 소진된 한도는 재시도 정보와 함께 HTTP 429를 반환할 수 있습니다.
참조 아키텍처
각 되돌릴 수 없는 결정에 한 명의 소유자를 지정하십시오
수신 및 신원
TLS를 종료하고, 서버가 보유한 키를 인증하며, 요청 상관 ID를 할당하고, 모든 작업을 하나의 계정에 바인딩하십시오.
정책 및 검증
권한 상태, 워크플로우 필드, 감지된 미디어 유형, 바이트 크기, 개수, 기간, 매핑, 계정 준비 상태 및 크레딧 가용성을 확인하십시오.
작업 원장
제어권을 반환하기 전에 taskId, 소유자, 워크플로우, 예상 요금, 상태 전환, 타임스탬프 및 정산 결과를 저장하십시오.
제한된 처리
요청 수락과 생성을 분리하고, 활성 작업을 제한하며, 재시도 가능한 전송 실패와 유효하지 않은 입력을 구분하십시오.
정산
예약, 완료 및 실패한 작업 환불 결정을 위해 하나의 원자적 권한을 사용하여 재시도가 두 번 청구하거나 환불하지 못하도록 하십시오.
전달 및 삭제
작업 소유자에 의한 결과 접근 권한 부여, 이미지 내보내기 권한 적용, 문서화된 24시간 일정에 따라 미디어 삭제
8단계 요청 순서
요청 계약에서 증거 기반 삭제로 전환
- 공개 요청 계약을 고정하십시오. 정확한 워크플로우와 기록 필드, 미디어 한도, 비용 단위 및 최종 상태를 선택하십시오.
- 권한 부여, 동의 및 계정 준비 상태를 확인하십시오. API 키를 서버 측에 보관하고 미디어를 수락하기 전에 권한 결정을 요구하십시오.
- 대기열에 넣기 전에 미디어를 검증하고 비용을 계산하십시오. 비용이 많이 드는 작업 전에 감지된 유형, 크기, 개수, 기간, 매핑 및 사용 가능한 크레딧을 검사하십시오.
- 하나의 내구성 있는 작업 기록을 생성하십시오. 소유권, 워크플로우, 예상 요금, 입력 참조, 상태 및 taskId를 저장하십시오.
- 제한된 대기열 뒤에서 비동기적으로 처리하십시오. 동시성을 제한하고 일시적 실패와 영구적 실패를 분류하십시오.
- 크레딧을 정확히 한 번 정산하십시오. 완료된 작업을 커밋하고 이중 정산 없이 문서화된 실패 처리 환불 경로를 적용하십시오.
- 소유자 범위의 상태 및 결과 액세스를 노출하십시오. 측정된 간격으로 폴링하고 COMPLETED, FAILED 또는 CANCELLED에서 중지하십시오.
- 삭제를 강제하고 운영 증거를 보유하십시오. 일정에 따라 미디어를 삭제하고 최소 허용 작업, 청구, 보안 및 지원 기록만 유지
상태 및 정산
처리 상태와 금전 상태를 분리하여 유지하십시오
| 이벤트 | 작업 기록 | 크레딧 조치 | 클라이언트 조치 |
|---|---|---|---|
| 작업 생성 전 요청 거부 | 수락된 작업 없음 | 요금을 추정하지 마십시오 | 요청 또는 계정 상태를 수정하십시오 |
| 작업 수락됨 | taskId 및 예상 비용 유지 | 정산을 서버 소유로 처리 | 측정된 폴링 시작 |
| 작업 완료됨 | 최종 결과 | 완료된 작업은 정산된 상태 유지 | 결과 검색 승인 |
| 처리 실패 | 최종 실패 | 현재 계약은 실패한 처리를 자동으로 환불 | 재제출 결정 전 실패 확인 |
| 응답 결과 불확실 | 다른 POST 전에 조정 | 타임아웃으로 추정하지 마십시오 | 저장된 taskId 또는 계정 기록 사용 |
공개 계약에 멱등성 키 필드가 문서화되어 있지 않습니다. 호출 서비스는 중복 제출을 비활성화하고, 첫 번째 taskId를 유지하며, 다른 POST를 발행하기 전에 불확실한 네트워크 응답을 조정해야 합니다.
장애 정책
실패 클래스가 허용하는 경우에만 재시도
| 상태 | 실패 클래스 | 아키텍처 응답 |
|---|---|---|
| 400 | 잘못된 요청 또는 미디어 | 필드 또는 미디어가 변경될 때까지 영구적으로 거부 |
| 401 / 403 | 키 또는 계정 준비 상태 | 키를 교체하거나 인증을 완료하십시오. 반복하지 마십시오. |
| 402 | 크레딧 부족 | 크레딧을 추가하고 확인 후에만 새 작업을 제출하십시오. |
| 404 | 잘못된 소유자, 경로 또는 taskId | 신원 및 저장된 작업 메타데이터를 조정하십시오. |
| 429 | 속도 또는 활성 생성 제한 | Retry-After가 제공되면 준수하고, 지터를 추가하며, 재시도 횟수를 제한하십시오. |
| 500 | 임시 수락 또는 읽기 실패 | 제한된 지수 백오프를 사용하고 중복 제출 전에 조정하십시오. |
관찰 가능성 및 보안
민감한 미디어를 로그에 복사하지 않고 제어 결정 추적
권장 작업 원격 측정에는 상관 ID, taskId, 계정 식별자, 워크플로, 정리된 미디어 사실, 예상 크레딧 금액, 상태 전환, 재시도 횟수, 오류 클래스, 정산 이벤트 및 삭제 타임스탬프가 포함됩니다. API 키, 얼굴 이미지, 완전한 업로드 파일 이름, 서명된 결과 URL 또는 멀티파트 본문을 기록하지 마십시오. W3C Trace Context 권장 사항 상호 운용 가능한 요청 컨텍스트를 정의합니다. 이는 DeepSwapAI의 비공개 구현에 대한 주장이 아닌 설계 옵션입니다.
업로드 방어를 위해 디코딩된 파일 이름, 감지된 콘텐츠, 허용된 형식, 개수 및 크기를 검증하십시오. 브라우저에서 제공하는 Content-Type만 신뢰하지 마십시오. OWASP File Upload Cheat Sheet 는 외부 보안 참조입니다. 동의 및 공개 계획 수립자 를 인간 승인 게이트로 사용하고 신뢰 센터 를 현재 공개 서비스 경계로 사용하십시오.
총 소유 비용
동일한 측정된 워크로드에서 관리형, 자체 호스팅 및 하이브리드 비교
API 요금을 원시 GPU 임대료와 단독으로 비교하지 마십시오. 먼저 하나의 워크로드 창을 고정하십시오: 워크플로 혼합, 미디어 지속 시간 및 해상도, 최대 동시성, 재시도율, 보존, 검토 볼륨 및 요구되는 가용성. 그런 다음 모든 반복 및 실패 관련 비용을 동일한 창에 할당하십시오.
| 비용 차원 | 관리형 API | 자체 호스팅 | 하이브리드 | 수집할 증거 |
|---|---|---|---|---|
| 처리 용량 | 게시된 작업 또는 기간 요금 | GPU 임대 또는 구매, 유휴 헤드룸, 확장 및 모델 런타임 | 내부 기준선에 외부 오버플로 또는 전문 처리 추가 | 완료된 단위, 기간, 해상도, 동시성 및 사용률 |
| 엔지니어링 및 운영 | 통합, 작업 유지, 폴링, 검토 및 공급업체 변경 처리 | 모델 서빙, 대기열, 업그레이드, 용량 계획, 배포 및 온콜 대응 | 오케스트레이션, 공급자 추상화 및 내부 플랫폼 소유권 | 측정된 엔지니어 시간, 릴리스 주기 및 온콜 부하 |
| 안전 및 거버넌스 | 애플리케이션 동의 게이트, 계정 정책, 검토 및 증거 | 모든 중재, 저장, 삭제, 액세스 제어 및 감사 통제 | 모든 결정에 명시적 소유자가 있는 공유 통제 | 검토 시간, 에스컬레이션율, 보존 범위 및 통제 소유자 |
| 저장 및 전달 | 애플리케이션 측 입력, 결과 및 네트워크 처리 | 입력, 중간, 결과, 백업, 이그레스, 삭제 작업 | 내부 기록에 제한된 공급자 전송 추가 | 보유 바이트, 전송 볼륨, 보존 시간 및 삭제 작업 |
| 실패 및 신뢰성 | 재시도, 조정, 공급자 중단 처리 및 전환 비용 | 중복, 사고 대응, 실패한 작업, 복구 및 미사용 용량 | 종속성 실패 및 내부 오케스트레이션 실패 모두 | 실패율, 복구 시간, 중복 작업 및 지원 부하 |
이 프레임워크는 자체 호스팅 가격 벤치마크를 게시하지 않으며 관리형, 자체 호스팅 또는 하이브리드가 보편적으로 더 저렴하다고 주장하지 않습니다. 결정은 동일한 기간에 대해 입증할 수 있는 워크로드 및 통제에 따라 달라집니다.
구축 결정
소유해야 하는 통제에 따라 관리형, 자체 호스팅 또는 하이브리드 선택
| 모델 | 귀하가 소유 | 외부 종속성 | 최적 적합 |
|---|---|---|---|
| 관리형 API | 동의 게이트, 애플리케이션 UX, 작업 유지, 폴링, 검토 및 비즈니스 정책 | 게시된 API, 제한, 가격 및 처리 동작 | 인프라 통제보다 통합 속도를 우선시하는 팀 |
| 자체 호스팅 | 모델, GPU 용량, 대기열, 중재, 저장, 보안, 정산, 삭제 및 사고 대응 | 모델 및 인프라 공급망 | 정당화된 통제 또는 배포 요구 사항 및 운영 용량이 있는 팀 |
| 하이브리드 | 내부 정책, 오케스트레이션, 감사 기록, 검토 및 공급자 추상화 | 하나 이상의 제한된 생성 서비스 | 모델 구성 요소를 운영하지 않고 애플리케이션 수준 통제가 필요한 팀 |
출처 및 방법
현재 제품 사실에 주요 외부 표준 추가
DeepSwapAI 제품 팀은 2026년 7월 22일에 다섯 가지 공개 경로, Bearer 인증, 멀티파트 요청, 작업 상태, 폴링 흐름, 오류 응답, 동시성 경계, 크레딧 정산, 평가판 이미지 자격 및 24시간 미디어 삭제를 확인했습니다. 권장 통제는 OpenAPI 사양 3.1.2, OWASP 업로드 지침, NIST AI RMF 1.0및 W3C Trace Context에 의해 정보를 얻었습니다. 현재 제품 진술이 일반 설계 지침과 어떻게 분리되는지는 주장 검증 방법론 을 참조하십시오.
아키텍처 질문
공개 계약이 무엇을 확립하고 확립하지 않는지 이해
이것이 DeepSwapAI의 비공개 프로덕션 아키텍처입니까?
아니요. 이는 공개 계약 설계 참조이며 공급자 토폴로지, 대기열 기술, 모델 배치, 작업자 수, 내부 네트워크 또는 서비스 수준 목표를 공개하지 않습니다.
클라이언트는 작업이 완료되었음을 어떻게 알 수 있습니까?
POST에서 반환된 taskId를 유지하고 동일한 워크플로 경로에서 COMPLETED, FAILED 또는 CANCELLED가 될 때까지 GET을 폴링하십시오. 웹훅 콜백은 현재 게시되지 않았습니다.
API 키를 클라이언트 코드에 배치할 수 있습니까?
아니요. 서버 측 비밀로 취급하고 브라우저 번들, 모바일 바이너리, 저장소, 분석, 로그 및 지원 메시지에서 멀리 유지하십시오.
API에서 멱등성 키를 게시합니까?
멱등성 키 필드가 문서화되지 않았습니다. 중복 제출을 방지하고, 첫 번째 taskId를 유지하며, 다른 POST 전에 불확실한 응답을 조정하십시오.
이 설계가 처리량 또는 품질을 보장합니까?
아니요. 이는 벤치마크, SLA, 정확도 점수 또는 품질 보장이 아닙니다.