인물 교체

새 장면을 만들어 내는 대신 화면 속 인물을 바꾸는 모델이 있습니다. 한 사진의 얼굴을 다른 사진으로 옮기거나, 머리 전체를 갈아 끼우거나, 영상 클립 속 인물을 통째로 교체합니다. 카탈로그는 이런 모델을 toolkit: "subject-swap" 이라는 하나의 라벨로 묶어 두었고, 형태는 두 가지입니다. 한 번에 끝나는 호출, 그리고 중간에 선택이 들어가는 두 번 호출입니다.

그 밖에 특별한 점은 없습니다. 평범한 비동기 작업이고, 매개변수는 각자의 inputSchema가 정하며, 결과는 output.assets[]로 돌아옵니다.

toolkit으로 이런 모델인지 알아내기

toolkit은 카탈로그 항목에 붙는 분류 라벨이며, 인증된 GET /api/v1/models 응답과 공개 카탈로그 모두에 담깁니다. 현재 값은 subject-swap 하나뿐이고, 어떤 툴킷에도 속하지 않는 모델에는 이 필드 자체가 없습니다. 키가 있는지가 아니라 값이 무엇인지로 판단하세요.

정보 전달용 필드일 뿐입니다. 어떤 키가 그 모델을 호출할 수 있는지, 요청이 어떻게 과금되는지, 모델이 무엇을 받아들이는지에는 관여하지 않습니다. 모르는 값이 오면 모르는 badges 항목과 똑같이 무시하세요.

curl -s "https://api.spicyapi.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  | jq -r '.data.items[]
      | select(.toolkit == "subject-swap" and .enabled and .available)
      | [.model, (.tasks | join(",")), .family] | @tsv'

한 줄이 호출 가능한 엔드포인트 하나입니다. 이 페이지의 나머지를 가르는 것은 tasks 열입니다. **video-analyze 엔드포인트가 있는 family는 두 번 호출하는 family**이며, 짝이 되는 video-edit 엔드포인트는 단독으로 호출할 수 없습니다.

지금 보고 있는 것은 어느 쪽인가

두 형태 모두 async: true입니다. 작업을 만든 뒤 폴링이나 webhook으로 결과를 받습니다.

한 번 호출

다른 편집 모델과 다를 것이 없습니다. 엔드포인트의 inputSchema를 읽고 값을 채워 작업을 만듭니다.

const created = await fetch('https://api.spicyapi.ai/api/v1/jobs/createTask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPICY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-8814-swap-1',
  },
  body: JSON.stringify({
    model: swap.model, // 위 카탈로그 조회에서 고른 항목
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

필드 이름은 엔드포인트마다 다릅니다. prompt나 seed, 출력 형식을 받는 것도 있고 사진 두 장 외에는 아무것도 받지 않는 것도 있습니다. 무엇을 보낼 수 있는지는 스키마가 전부이니, 한 엔드포인트의 필드 이름을 다른 엔드포인트로 옮겨 쓰지 마세요. 참조 이미지로는 공개된 HTTPS URL, 작은 이미지의 인라인 Base64, 업로드해 둔 spicy:// URI를 쓸 수 있습니다. 미디어를 참고하세요.

두 번 호출

첫 호출은 클립을 살펴보고 무엇을 찾았는지를 순서가 있는 미리보기 스틸로 알려 줍니다. 그중 무엇을 바꿀지는 여러분이 정합니다. 실제 작업은 두 번째 호출이 합니다.

내 클립 ──▶ video-analyze ──▶ output.assets[0], [1], [2] …（대상 하나당 스틸 한 장）
                                          │
                        0번과 2번 선택 ──▶│
                                          ▼
           video-edit（analysis_task_id + swap_targets）──▶ 완성된 클립

왜 한 번에 하지 않을까요. 네 사람이 있는 장면에서 한 번 호출은 여러분이 누구를 뜻했는지 추측할 수밖에 없고, 추측이 빗나가면 엉뚱한 사람이 바뀐 영상이 완성되어 그대로 과금됩니다. 작업을 둘로 나누면 선택이 겉으로 드러나고 눈으로 확인할 수 있습니다.

const analysis = await createTask({
  model: analyze.model, // tasks에 "video-analyze"가 들어 있는 항목
  input: {
    video_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
    resolution: '720p',
  },
});
const analysisTaskId = analysis.taskId;

{
  "state": "succeeded",
  "output": {
    "assets": [
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" },
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" }
    ]
  },
  "settled": true
}

const swapped = await createTask({
  model: edit.model, // 같은 family에 있는 "video-edit" 항목
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // 분석을 실행한 값과 동일하게
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

두 번째 호출이 받아들이기 전에 확인하는 것

이 확인은 작업을 만드는 시점에 이루어지므로, 거절된 요청은 아무것도 만들지 않고 아무 금액도 예약하지 않습니다.

두 번째 호출이 거절될 때

모두 HTTP 400이고 업무 코드도 code: 400입니다. msg는 다음 중 하나입니다.

두 호출의 비용

분석과 교체는 가격이 각각 따로 붙는 두 개의 작업이며, 예약과 정산도 따로 이루어집니다. 두 번째 호출이 거절되면 비용은 들지 않지만, 분석이 성공한 뒤 교체를 그만두더라도 분석 비용은 청구됩니다.

• 분석은 보통 per_request입니다. 클립 길이나 찾아낸 대상 수와 무관하게 호출 한 번에 한 건입니다.
• 교체는 보통 per_second이며 정해진 묶음(블록) 단위로 셉니다. 길이는 여러분이 지정하는 필드가 아니라 클립 자체에서 나오므로, 미리 안내되는 금액은 그 엔드포인트가 받아들이는 가장 긴 클립을 기준으로 한 값입니다. 안내된 금액이 그대로 예약되고, 최종 청구액은 올림한 길이로 계산되어 예약 금액을 넘지 않으며, 차액은 작업이 정산될 때 잔액으로 돌아옵니다. 여기서 예약 금액이 최종 청구액보다 크게 보이는 것은 정상입니다. 예산을 잡기 전에 과금을 먼저 읽어 보세요.

두 가격 모두 짐작하지 말고 카탈로그에서 읽고, 정확한 금액이 중요하다면 호출마다 견적을 받아 두세요.

다음 단계