소개
Video Character Swap Analysis는 클립을 읽어 추적할 수 있는 인물마다 미리보기 스틸을 한 장씩, 정해진 순서로 돌려줍니다. 첫 장이 위치 0, 두 번째가 위치 1이고 그다음도 같습니다. 교체 호출이 받는 것이 바로 이 위치 번호입니다. 사진을 보고 번호를 돌려보내면 됩니다.
여기서는 아무것도 생성되지 않고 클립도 바뀌지 않습니다. 이 호출은 교체 호출이 작업할 대상 목록을 만들며, 한 장면에 몇 명이 있고 그중 누가 누구인지 알아내는 방법은 이것뿐입니다.
핵심 기능 및 하이라이트
좌표가 아니라 사진에서 고릅니다
이런 종류의 엔드포인트는 대개 누구를 뜻했는지 설명하게 하거나 스스로 추측합니다. 여기서는 분석이 후보를 번호가 매겨진 이미지로 건네줍니다. 누구를 교체할지에 대한 모호함이 무엇이든 생성되기 전에 풀리며, 그 시점은 실수해도 아직 비용이 들지 않는 시점이기도 합니다.
분석 한 번으로 여러 번 교체합니다
결과는 24시간 동안 그대로 쓸 수 있습니다. 한 사람을 넣어 결과를 본 다음, 같은 분석에 다른 참조 사진을 보내면 됩니다. 분석 요금은 한 번만 냅니다. 24시간이 지나면 참조가 만료되어 클립을 다시 분석해야 합니다.
촬영된 그대로 읽습니다
추적은 컷 전환과 몸을 돌리는 동작, 부분적인 가림을 지나 각 인물을 계속 따라갑니다. 5~30초 클립을 받으며, 분석은 앞에 선 한 명만이 아니라 장면이 이어지는 동안 붙잡고 있을 수 있었던 인물을 모두 보고합니다.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
video_url | 예 | 분석할 클립이며 5~30초입니다. 이 URL을 그대로 보관하십시오. 1자 이상 |
resolution | 아니요 | 추적 해상도입니다. 교체 호출도 같은 값을 써야 하므로 완성 클립에 주고 싶은 해상도를 고르십시오. |
요금
$0.08 / 분석
분석과 교체는 각각 따로 과금됩니다.
활용 사례
돈을 들여 교체하기 전에 클립 확인하기
교체 호출은 분석보다 비쌉니다. 분석을 먼저 돌리면 관심 있는 인물이 이 영상에서 실제로 추적되는지 알 수 있습니다. 심한 흔들림, 긴 가림, 화면 밖으로 나가는 피사체는 미리보기가 빠지거나 불안정해지는 형태로 드러납니다.
여러 사람 중 한 명만 고르기
여러 사람이 나오는 장면을 분석하고 미리보기를 읽은 뒤, 의도한 위치만 돌려보냅니다. 나머지는 교체의 손을 타지 않습니다.
시리즈 전체에서 같은 배역 유지하기
어떤 영상 모델로든 클립을 여러 개 만들고 각각 분석한 다음, 미리보기를 보고 모든 장면에서 같은 대상을 맞춥니다. 시리즈가 하나로 이어지게 읽힙니다.
동의한 출연자라면 어떤 소재든
영상에 무엇이 담겼든 요청은 달라지지 않습니다. 아래 제한에 적힌 허락 요건도 달라지지 않습니다. 이것은 콘텐츠 등급이 아니라 반드시 지켜야 할 조건입니다.
프롬프트 가이드 및 실전 팁
두 호출에서 같은 해상도를 씁니다
완성된 클립에 주고 싶은 해상도를 정하고 여기서도 같은 값을 쓰십시오. 교체 호출이 같은 값으로 실행되어야 합니다. 이 호출이 무엇을 찾아내는지는 달라지지 않고, 달라지는 것은 교체가 작업할 화면뿐입니다.
미리보기 순서는 읽어야 하며 짐작하면 안 됩니다
스틸은 순서대로 돌아오지만 그 순서는 추적의 결과이지 화면상의 위치나 비중이 아닙니다. 화면 맨 왼쪽 사람이 반드시 위치 0인 것은 아닙니다. 이미지를 직접 보십시오.
같은 영상을 두 호출에 보냅니다
교체 호출에는 똑같은 클립이 필요합니다. 같은 파일, 같은 인코딩이어야 합니다. 교체 요청에서 video_url을 빼면 분석에서 그대로 이어받으므로, 두 호출이 일치한다고 보장하는 가장 안전한 방법입니다.
영상이 바뀌면 다시 분석합니다
다시 인코딩하거나 자르거나 다시 내보내면 분석은 무효가 됩니다. 위치 번호가 더 이상 같은 인물을 가리키지 않기 때문입니다. 실제로 교체할 파일을 그대로 분석하십시오.
API 빠른 시작
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/character-swap-v1/video-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
인증, 전체 스키마, 폴링과 오류 처리는 API 레퍼런스에서 확인하세요.