Podmiana osoby

Część modeli nie generuje nowej sceny, tylko podmienia osobę: przenosi twarz z jednego zdjęcia na drugie, wymienia całą głowę albo zastępuje całą postać w klipie wideo. Katalog zbiera je pod jedną etykietą, toolkit: "subject-swap", a występują w dwóch postaciach — jedno wywołanie albo dwa wywołania z wyborem pomiędzy nimi.

Poza tym nie mają w sobie nic wyjątkowego. To zwykłe zadania asynchroniczne, parametry pochodzą z ich własnego inputSchema, a wyniki trafiają do output.assets[].

toolkit mówi, że model należy do tej grupy

toolkit to etykieta klasyfikująca przy pozycji katalogu, obecna zarówno w uwierzytelnionej odpowiedzi GET /api/v1/models, jak i w katalogu publicznym. Dziś ma jedną wartość, subject-swap, a przy modelach spoza jakiegokolwiek zestawu tego pola w ogóle nie ma — sprawdzaj więc wartość, nigdy obecność klucza.

Pole jest wyłącznie informacyjne. Nie rozstrzyga, który klucz może wywołać model, jak wyceniane jest żądanie ani co model przyjmuje. Nieznaną wartość potraktuj tak jak nieznany wpis w badges: pomiń ją.

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'

Każdy wiersz to jeden wywoływalny endpoint. O reszcie tej strony decyduje kolumna tasks: family z endpointem video-analyze to family dwuwywołaniowa, a towarzyszącego jej endpointu video-edit nie da się wywołać samodzielnie.

Którą postać mam przed sobą?

Obie postaci mają async: true: tworzysz zadanie, a wynik odbierasz odpytywaniem albo webhookiem.

Jedno wywołanie

Nic tu nie odbiega od dowolnego innego modelu edycyjnego. Przeczytaj inputSchema endpointu, wypełnij je i utwórz zadanie:

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, // jedna z pozycji z powyższego zapytania do katalogu
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

Nazwy pól różnią się między endpointami: jedne przyjmują prompt, seed albo format wyjścia, inne nic poza dwoma obrazami. Obowiązującą listą jest schemat; nie przenoś nazw pól z jednego endpointu na drugi. Referencją może być publiczny adres HTTPS, mały obraz w Base64 wpisany wprost w żądanie albo przesłany wcześniej URI spicy://; zobacz Pliki multimedialne.

Dwa wywołania

Pierwsze wywołanie ogląda twój klip i zgłasza, co w nim znalazło, w postaci uporządkowanego zestawu klatek podglądu. To ty decydujesz, które z nich podmienić. Właściwą pracę wykonuje drugie wywołanie.

twój klip ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (jedna klatka na cel)
                                          │
                        wybierasz pozycje │ 0 i 2
                                          ▼
          video-edit (analysis_task_id + swap_targets) ──▶ gotowy klip

Dlaczego nie jednym wywołaniem? Bo w scenie z czterema osobami pojedyncze wywołanie musiałoby zgadywać, kogo miałeś na myśli, a chybione zgadywanie to gotowy, rozliczony film z podmienioną niewłaściwą osobą. Rozbicie pracy na dwa kroki czyni wybór jawnym i możliwym do sprawdzenia.

const analysis = await createTask({
  model: analyze.model, // pozycja, której tasks zawierają "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, // pozycja "video-edit" z tej samej family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // ta sama wartość, na której działała analiza
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

Co drugie wywołanie sprawdza, zanim je przyjmie

Te kontrole odbywają się przy tworzeniu zadania, więc odrzucone żądanie niczego nie tworzy i niczego nie blokuje.

Gdy drugie wywołanie zostaje odrzucone

Wszystkie te przypadki to HTTP 400 z kodem biznesowym code: 400. Pole msg przyjmuje jedną z wartości:

Ile kosztują oba wywołania

Analiza i podmiana to dwa osobne zadania z dwiema osobnymi cenami, każde z własną blokadą i własnym rozliczeniem. Odrzucone drugie wywołanie nic nie kosztuje; udana analiza zostaje rozliczona nawet wtedy, gdy potem zrezygnujesz z podmiany.

• Analiza jest zwykle wyceniana per_request: jedno obciążenie na wywołanie, niezależnie od długości klipu i liczby znalezionych celów.
• Podmiana jest zwykle wyceniana per_second, w pełnych blokach, a długość bierze się z klipu, a nie z pola, które ustawiasz. Kwota podana przed wysłaniem dotyczy więc najdłuższego klipu, jaki endpoint przyjmuje: podana kwota jest kwotą zablokowaną, końcowe obciążenie liczy się z długości zaokrąglonej w górę i nigdy nie przekracza blokady, a różnica wraca na saldo przy rozliczeniu zadania. Blokada większa od końcowego obciążenia jest tutaj zachowaniem oczekiwanym. Zanim zaplanujesz na tym budżet, przeczytaj Rozliczenia.

Obie ceny odczytaj z katalogu, zamiast je zakładać, a jeśli liczy się dokładna kwota, poproś o wycenę każdego wywołania.

Następne kroki