Personen austauschen

Manche Modelle erzeugen keine neue Szene, sondern ersetzen eine Person: ein Gesicht, das von einem Foto auf ein anderes wandert, ein ganzer Kopf oder eine komplette Figur in einem Videoclip. Der Katalog fasst sie unter einem Label zusammen, toolkit: "subject-swap", und es gibt sie in zwei Formen — ein Aufruf oder zwei Aufrufe mit einer Entscheidung dazwischen.

Sonst ist nichts Besonderes an ihnen. Es sind gewöhnliche asynchrone Tasks, ihre Parameter stehen im jeweils eigenen inputSchema, und ihre Ergebnisse kommen in output.assets[] an.

toolkit verrät, dass ein Modell dazugehört

toolkit ist ein Klassifizierungslabel an einem Katalogeintrag und steht sowohl in der authentifizierten Antwort von GET /api/v1/models als auch im öffentlichen Katalog. Heute gibt es genau einen Wert, subject-swap, und bei Modellen ohne Toolkit fehlt das Feld ganz — prüfen Sie also auf den Wert, nie auf den Schlüssel.

Das Feld ist rein informativ. Es entscheidet weder darüber, welcher Schlüssel ein Modell aufrufen darf, noch wie eine Anfrage bepreist wird oder was das Modell annimmt. Behandeln Sie einen unbekannten Wert wie einen unbekannten Eintrag in badges: ignorieren Sie ihn.

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'

Jede Zeile ist ein aufrufbarer Endpunkt. Über den Rest dieser Seite entscheidet die Spalte tasks: Eine family mit einem video-analyze-Endpunkt ist eine family mit zwei Aufrufen, und ihr zugehöriger video-edit-Endpunkt lässt sich nicht allein aufrufen.

Welche Form liegt vor?

Beide Formen sind async: true: Sie erstellen einen Task und holen das Ergebnis per Polling oder Webhook ab.

Ein Aufruf

Hier unterscheidet sich nichts von anderen Bearbeitungsmodellen. Lesen Sie das inputSchema des Endpunkts, füllen Sie es aus, erstellen Sie den 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, // ein Eintrag aus der Katalogabfrage oben
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

Die Feldnamen unterscheiden sich von Endpunkt zu Endpunkt: Manche nehmen einen prompt, einen seed oder ein Ausgabeformat, manche nichts außer den beiden Bildern. Maßgeblich ist allein das Schema; übernehmen Sie Feldnamen nicht von einem Endpunkt auf den nächsten. Referenzen können eine öffentliche HTTPS-URL sein, ein kleines Bild direkt als Base64 oder eine hochgeladene spicy://-URI; siehe Medien.

Zwei Aufrufe

Der erste Aufruf sieht sich Ihren Clip an und meldet, was er gefunden hat — als geordnete Folge von Vorschau-Standbildern. Sie entscheiden, welche davon ersetzt werden. Die eigentliche Arbeit macht der zweite Aufruf.

Ihr Clip ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (ein Standbild je Ziel)
                                          │
                Sie wählen die Positionen │ 0 und 2
                                          ▼
           video-edit (analysis_task_id + swap_targets) ──▶ der fertige Clip

Warum nicht in einem Aufruf? Weil ein einzelner Aufruf bei vier Personen im Bild raten müsste, wen Sie meinen — und ein falscher Tipp ergibt ein fertiges, abgerechnetes Video, in dem die falsche Person ersetzt wurde. Die Aufteilung macht die Wahl ausdrücklich und überprüfbar.

const analysis = await createTask({
  model: analyze.model, // der Eintrag, dessen tasks "video-analyze" enthält
  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, // der "video-edit"-Eintrag derselben family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // derselbe Wert, mit dem die Analyse lief
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

Was der zweite Aufruf vor der Annahme prüft

Diese Prüfungen laufen beim Erstellen, eine abgelehnte Anfrage erzeugt also nichts und reserviert nichts.

Wenn der zweite Aufruf abgelehnt wird

Alle Fälle sind HTTP 400 mit dem Geschäftscode code: 400. msg ist einer der folgenden Werte:

Was die beiden Aufrufe kosten

Analyse und Austausch sind zwei getrennte Tasks mit zwei getrennten Preisen, jeder für sich reserviert und abgerechnet. Ein abgelehnter zweiter Aufruf kostet nichts; eine erfolgreiche Analyse wird berechnet, auch wenn Sie danach auf den Austausch verzichten.

• Die Analyse wird meist per_request bepreist — eine Abrechnung je Aufruf, gleich wie lang der Clip ist und wie viele Ziele sie findet.
• Der Austausch wird meist per_second bepreist, in ganzen Blöcken, und die Länge kommt aus dem Clip statt aus einem Feld, das Sie setzen. Der vorab genannte Betrag gilt deshalb für den längsten Clip, den der Endpunkt annimmt: Der genannte Betrag ist der reservierte Betrag, die endgültige Abrechnung entsteht aus der aufgerundeten Dauer und übersteigt die Reservierung nie, und die Differenz kehrt beim Abrechnen in Ihr Guthaben zurück. Eine Reservierung, die größer ist als die spätere Abrechnung, ist hier zu erwarten. Lesen Sie Abrechnung, bevor Sie damit planen.

Lesen Sie beide Preise aus dem Katalog, statt sie anzunehmen, und holen Sie für jeden Aufruf eine Kostenschätzung ein, wenn es auf den genauen Betrag ankommt.

Nächste Schritte