Subject swap

Some models replace a person instead of generating a new scene: a face carried from one photo onto another, a whole head, or a whole figure in a video clip. The catalog groups them under one label, toolkit: "subject-swap", and they come in two shapes — one call, or two calls with a choice in between.

Nothing else about them is special. They are ordinary asynchronous tasks, their parameters come from their own inputSchema, and their results arrive in output.assets[].

toolkit tells you the model is one of these

toolkit is a classification label on a catalog item, present in both the authenticated GET /api/v1/models response and the public catalog. Today it has one value, subject-swap, and the field is absent on models that belong to no toolkit — so test for the value, never for the key.

It is informational only. It does not affect which key may call a model, how the request is priced, or what the model accepts. Treat an unfamiliar value the same way you treat an unfamiliar badges entry: ignore it.

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'

Every line is one callable endpoint. The tasks column is what decides the rest of this page: a family that has a video-analyze endpoint is a two-call family, and its companion video-edit endpoint cannot be called on its own.

Which shape am I looking at?

Both shapes are async: true: you create a task, then collect the result by polling or webhook.

One call

Nothing here differs from any other editing model. Read the endpoint's inputSchema, fill it in, create the task:

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, // one item from the catalog query above
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

Field names differ between endpoints — some take a prompt, a seed or an output format, some take nothing but the two pictures. The schema is the list; do not carry field names over from one endpoint to another. References can be a public HTTPS URL, a small inline Base64 image or an uploaded spicy:// URI; see Media.

Two calls

The first call looks at your clip and reports what it found, as an ordered set of preview stills. You decide which of those to replace. The second call does the work.

your clip ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (one still per target)
                                          │
                        you pick positions │ 0 and 2
                                          ▼
            video-edit (analysis_task_id + swap_targets) ──▶ the finished clip

Why not one call? Because in a scene with four people, one call would have to guess which one you meant, and a wrong guess is a finished, billed video of the wrong person being replaced. Splitting the job makes the choice explicit and reviewable.

const analysis = await createTask({
  model: analyze.model, // the item whose tasks include "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, // the "video-edit" item in the same family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // the same value the analysis ran at
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

What the second call checks before it accepts

These checks run at creation, so a rejected request creates nothing and holds nothing.

When the second call is rejected

All of these are HTTP 400 with business code: 400. The msg is one of:

What the two calls cost

The analysis and the swap are two separate tasks with two separate prices, each held and settled on its own. A rejected second call costs nothing; a successful analysis is charged even if you then decide not to swap anything.

• The analysis is usually priced per_request — one charge per call, whatever the clip's length and however many targets it finds.
• The swap is usually priced per_second, in whole blocks, and the length comes from the clip rather than from a field you set. So the amount quoted up front is the longest clip the endpoint accepts: the quoted amount is the amount held, the final charge is computed from the rounded duration and never exceeds the hold, and the difference returns to your balance when the task settles. Seeing a hold larger than the final charge is expected here. Read Length billed in whole blocks before you budget for it.

Read both prices from the catalog rather than assuming, and quote each call if the exact number matters.

Next steps