Cast Swap

The Cast Swap API replaces the people, the location, or both in a short video with your own reference images. The video keeps its motion, framing, timing and sound. You quote a run for free, start it, and follow its job like any other.

Cast Swap runs on Nodaro Cloud only. On a self-hosted install, both routes answer 404. The routes take a bearer token. See Authentication.

Endpoints

The request body

Both routes take the same body.

A role names someone, or the setting, in the video, and takes 0 to 3 images of one person or one place:

• A person: { kind: "person", name, images, body?, outfit?, hair? }. name says who in the video, for example "the woman dancing". Each of body, outfit and hair is "new", the default, which takes it from your images, or "original", which keeps it from the video.
• The location: { kind: "location", name?, images }. The default name is "the setting".

A role with no images, empty or null, keeps that person or place as in the video. At least one role with images, or a postPrompt, is required.

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

The quote

POST /v1/cast-swap/estimate answers { totalCredits, breakdown: { castSwap, seedance }, settlesLower }.

• totalCredits is breakdown.castSwap, the run itself, plus breakdown.seedance, the video model it calls.
• settlesLower: true means the length of the result is left to the model, so the final charge is expected to be lower than the quote.

Repeats

Send the same Idempotency-Key header, 8 to 200 characters, when you retry a run. A repeat within about 10 seconds answers 200 { jobId, deduped: true } with an X-Dedup-Hit: 1 header. A later repeat answers 202 { jobId } with the first run's job. Either way, nothing new is started or charged. Without a key, every request is a new run.

Errors

Every refusal comes before anything is charged. The body is { error: { code, message } }.

From the SDK

client.castSwap wraps both routes. It is also importable as @nodaro/sdk/cast-swap.

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

CastSwapParams is the request body above. CastSwapEstimate is the quote. run() sends idempotencyKey unchanged as the Idempotency-Key header. Without it, no header is sent.

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() })

Follow the job with client.jobs.get(jobId). A preview's job keeps every input in its input_data, so you can run it again with preview: false to render the full clip with the same choices.

From MCP

The MCP tool is cast_swap. Without confirm, it returns the quote and charges nothing. With confirm: true, after the user accepts the price, it starts the run and returns a job id.