Cast Swap

Cast Swap API는 짧은 동영상 속 인물, 장소 또는 둘 다를 내 레퍼런스 이미지로 교체합니다. 동영상의 움직임, 구도, 타이밍, 소리는 그대로 유지됩니다. 실행 견적을 무료로 받고, 실행을 시작한 뒤, 다른 작업처럼 그 작업을 추적하세요.

Cast Swap은 Nodaro Cloud에서만 실행됩니다. 셀프 호스팅 설치에서는 두 라우트 모두 404로 응답합니다. 라우트는 Bearer 토큰을 받습니다. 인증을 참조하세요.

엔드포인트

요청 본문

두 라우트는 같은 본문을 받습니다.

역할은 동영상 속 누군가나 배경을 지정하며, 한 사람이나 한 장소의 이미지를 0~3장 받습니다.

• 인물: { kind: "person", name, images, body?, outfit?, hair? }. name은 동영상 속 누구인지를 말합니다. 예: "the woman dancing". body, outfit, hair는 각각 내 이미지에서 가져오는 기본값 "new", 또는 동영상에서 유지하는 "original"입니다.
• 장소: { kind: "location", name?, images }. 기본 이름은 "the setting"입니다.

이미지가 없는(비어 있거나 null인) 역할은 그 인물이나 장소를 동영상 그대로 유지합니다. 이미지가 있는 역할이 하나 이상 있거나 postPrompt가 있어야 합니다.

{
  "videoUrl": "https://example.com/clip.mp4",
  "roles": [
    { "kind": "person", "name": "the woman dancing", "images": ["https://example.com/me.jpg"], "outfit": "original" }
  ],
  "preview": true
}

견적

POST /v1/cast-swap/estimate는 { totalCredits, breakdown: { castSwap, seedance }, settlesLower }로 응답합니다.

• totalCredits는 실행 자체인 breakdown.castSwap과, 실행이 호출하는 동영상 모델인 breakdown.seedance를 더한 값입니다.
• settlesLower: true는 결과의 길이를 모델이 정한다는 뜻이므로, 최종 청구액이 견적보다 낮을 것으로 예상됩니다.

반복 요청

실행을 재시도할 때는 8~200자의 같은 Idempotency-Key 헤더를 보내세요. 약 10초 안에 반복된 요청은 X-Dedup-Hit: 1 헤더와 함께 200 { jobId, deduped: true }로 응답합니다. 그 뒤에 반복된 요청은 첫 실행의 작업으로 202 { jobId }라고 응답합니다. 어느 경우든 새로 시작되거나 청구되는 것은 없습니다. 키가 없으면 요청마다 새 실행이 됩니다.

오류

모든 거부는 아무것도 청구되기 전에 일어납니다. 본문은 { error: { code, message } }입니다.

SDK에서 사용

client.castSwap은 두 라우트를 감쌉니다. @nodaro/sdk/cast-swap으로도 가져올 수 있습니다.

run(params: CastSwapParams, options?: { idempotencyKey?: string }): Promise<{ jobId: string; deduped?: boolean }>
estimate(params: CastSwapParams): Promise<CastSwapEstimate>

CastSwapParams는 위의 요청 본문입니다. CastSwapEstimate는 견적입니다. run()은 idempotencyKey를 그대로 Idempotency-Key 헤더로 보냅니다. 없으면 헤더를 보내지 않습니다.

const params: CastSwapParams = {
  videoUrl,
  roles: [{ kind: "person", name: "the woman dancing", images: [myPhotoUrl], outfit: "original" }],
  preview: true,
}
const quote = await client.castSwap.estimate(params)
const { jobId } = await client.castSwap.run(params, { idempotencyKey: crypto.randomUUID() })

client.jobs.get(jobId)로 작업을 추적하세요. 미리보기 작업은 모든 입력을 input_data에 보관하므로, preview: false로 다시 실행해 같은 선택으로 클립 전체를 렌더링할 수 있습니다.

MCP에서 사용

MCP 도구는 cast_swap입니다. confirm이 없으면 견적을 반환하고 아무것도 청구하지 않습니다. 사용자가 가격을 수락한 뒤 confirm: true로 호출하면 실행을 시작하고 작업 ID를 반환합니다.