Remplacement de personne

Certains modèles ne créent pas une scène : ils remplacent une personne. Un visage repris d’une photo et posé sur une autre, une tête entière, ou toute une silhouette dans un clip vidéo. Le catalogue les regroupe sous une même étiquette, toolkit: "subject-swap", et ils existent en deux formes — un appel, ou deux appels avec un choix entre les deux.

Rien d’autre ne les distingue. Ce sont des tâches asynchrones ordinaires, leurs paramètres viennent de leur propre inputSchema et leurs résultats arrivent dans output.assets[].

toolkit vous dit que le modèle en fait partie

toolkit est une étiquette de classification posée sur une entrée du catalogue, présente aussi bien dans la réponse authentifiée de GET /api/v1/models que dans le catalogue public. Elle n’a aujourd’hui qu’une valeur, subject-swap, et le champ est absent sur les modèles qui n’appartiennent à aucune boîte à outils : testez donc la valeur, jamais la présence de la clé.

Le champ est purement informatif. Il ne décide ni de la clé autorisée à appeler un modèle, ni du prix de la requête, ni de ce que le modèle accepte. Traitez une valeur inconnue comme une entrée badges inconnue : ignorez-la.

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'

Chaque ligne correspond à un point de terminaison appelable. C’est la colonne tasks qui détermine tout le reste de cette page : une family qui possède un point de terminaison video-analyze est une family à deux appels, et son point de terminaison video-edit associé ne s’appelle pas seul.

Quelle forme ai-je sous les yeux ?

Les deux formes sont en async: true : vous créez une tâche, puis récupérez le résultat par interrogation ou par webhook.

Un appel

Rien ne change par rapport à n’importe quel autre modèle d’édition. Lisez l’inputSchema du point de terminaison, remplissez-le, créez la tâche :

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, // une entrée de la requête catalogue ci-dessus
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

Les noms de champs varient d’un point de terminaison à l’autre : certains acceptent un prompt, un seed ou un format de sortie, d’autres rien d’autre que les deux images. Le schéma fait foi ; ne transposez pas les noms de champs d’un point de terminaison à un autre. Une référence peut être une URL HTTPS publique, une petite image en Base64 directement dans la requête, ou une URI spicy:// téléversée ; voir Médias.

Deux appels

Le premier appel examine votre clip et rapporte ce qu’il y a trouvé, sous la forme d’un ensemble ordonné d’images fixes de prévisualisation. Vous décidez lesquelles remplacer. Le second appel fait le travail.

votre clip ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (une image par cible)
                                          │
            vous choisissez les positions │ 0 et 2
                                          ▼
          video-edit (analysis_task_id + swap_targets) ──▶ le clip terminé

Pourquoi ne pas tout faire en un appel ? Parce que dans une scène à quatre personnes, un appel unique devrait deviner laquelle vous visiez, et une mauvaise devinette donne une vidéo terminée et facturée où c’est la mauvaise personne qui a été remplacée. Scinder le travail rend le choix explicite et vérifiable.

const analysis = await createTask({
  model: analyze.model, // l’entrée dont les tasks contiennent "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, // l’entrée "video-edit" de la même family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // la valeur à laquelle l’analyse a tourné
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

Ce que le second appel vérifie avant d’accepter

Ces vérifications ont lieu à la création : une requête refusée ne crée rien et ne réserve rien.

Quand le second appel est refusé

Tous ces cas sont des HTTP 400 avec le code métier code: 400. Le champ msg vaut l’une des valeurs suivantes :

Ce que coûtent les deux appels

L’analyse et le remplacement sont deux tâches distinctes à deux prix distincts, réservées et réglées chacune de leur côté. Un second appel refusé ne coûte rien ; une analyse réussie est facturée même si vous renoncez ensuite à remplacer quoi que ce soit.

• L’analyse est en général tarifée per_request : une facturation par appel, quelle que soit la durée du clip et quel que soit le nombre de cibles trouvées.
• Le remplacement est en général tarifé per_second, par blocs entiers, et la durée vient du clip et non d’un champ que vous renseignez. Le montant annoncé avant l’envoi correspond donc au clip le plus long que le point de terminaison accepte : le montant annoncé est le montant réservé, la facturation finale se calcule sur la durée arrondie et ne dépasse jamais la réservation, et la différence revient sur votre solde au règlement de la tâche. Voir ici une réservation supérieure à la facturation finale est normal. Lisez Facturation avant d’établir un budget.

Lisez les deux prix dans le catalogue au lieu de les supposer, et demandez un devis pour chaque appel si le montant exact compte.

Étapes suivantes