Pro API: generowanie i retusz obrazów

Jeden obraz kosztuje 1 kredyt, niezależnie od trybu. Generowanie na podstawie promptu oraz retusz dostarczonego obrazu przebiegają przez tę samą ścieżkę.

POST /images/quote przyjmuje to samo ciało żądania i zwraca cenę bez tworzenia czegokolwiek, zawsze { "cost": 1, ... } w tym przypadku. Istnieje dla symetrii z filmami, gdzie cena może się różnić.

Prześlij obraz

POST /images

{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
  "width": 832, "height": 1216 }

Odpowiedź:

{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }

seed jest zwracany w odpowiedzi, niezależnie od tego, czy go podałeś, czy został wylosowany: zachowaj go, aby wyrenderować ten sam obraz ponownie lub jego wariację.

Żądanie kilku obrazów naraz

Przy count większym niż 1 jedno żądanie uruchamia kilka renderowań, każde z własnym seedem, a odpowiedź je wymienia:

{ "count": 4, "requested": 4, "cost_total": 4,
  "jobs": [ { "jobId": "...", "seed": 178078967, "cost": 1 }, { "jobId": "...", "seed": 903412, "cost": 1 } ],
  "errors": [],
  "jobId": "...", "seed": 178078967, "cost": 1 }

Dwie rzeczy wymagają szczególnej uwagi.

jobId, seed i cost pierwszego renderowania są powtórzone na najwyższym poziomie. Wynika to z tego, żeby klienci napisani przed obsługą wsadową nadal działali bez zmian, a nie dlatego, że pierwsze renderowanie jest ważniejsze. Odpytuj każdy wpis w jobs, a nie tylko ten jeden.

I porównuj count z requested. Odmowa w trakcie przetwarzania, z powodu braku kredytów lub przekroczenia dziennego limitu klucza, zatrzymuje wsad w miejscu: requested to to, o co prosiłeś, count to ile faktycznie się uruchomiło, a errors wyjaśnia, dlaczego się zatrzymało. Klient, który zakłada, że obie wartości są równe, po cichu traci renderowania.

POST /images/quote przyjmuje też count i wycenia cały wsad. Filmy nie mają count: jedno żądanie, jeden klip.

Trzy tryby retuszu

Wszystkie trzy działają na tym samym silniku edycji opartym na instrukcjach, który zachowuje wygląd obrazu źródłowego. Gdy dostarczasz obraz źródłowy, width i height są odczytywane z samego obrazu i nie trzeba ich przesyłać.

W trybie edit serwer sam wybiera najlepszy sposób obróbki, tak jak aplikacja:

• z maską: czyta polecenie i wybiera między zastąpieniem zawartości obszaru (inny przedmiot, inne ubranie, twarz: obszar jest rysowany od nowa według tego, co ma się w nim pojawić) a zmianą tego, co w nim jest (kolor, materiał, światło). Z lora postaci obszar jest zawsze rysowany od nowa, razem z twarzą;
• bez maski, z lora postaci ("replace the woman with kara..."): serwer znajduje osobę na zdjęciu i rysuje ją od nowa jako postać; jeśli nikogo nie znajdzie, polecenie dotyczy całego obrazu, jak dotąd.

Ta sama cena w każdym przypadku (1 kredyt za obraz). Wybór widać w wyniku, nie w odpowiedzi.

IMG=$(base64 -w0 photo.png)
curl -s $B/images -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d "{\"mode\":\"edit\",\"prompt\":\"add a red scarf, keep everything else identical\",\"image_b64\":\"$IMG\"}"

Tworzenie obrazu z postaciami, przedmiotami i miejscem

Dodaj obiekt multiref do POST /images, a serwer obsadzi Twoje postacie (Postacie), Twoje przedmioty i zwierzęta oraz miejsce (Obiekty) razem na jednym obrazie, każde rozpoznawalne, tak jak ekran "Utwórz obraz" w aplikacji. Wywołuj każde z nich przez @Nazwa w prompcie, po angielsku.

{ "prompt": "@Mia hands a cup of coffee to @Tom on a sunny terrace, both smiling",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Mia", "view": 1 },
      { "character_id": "chr_21bc...", "name": "Tom", "lora": "tom_v1", "strength": 1.0, "lora_pass": 0.55 }
    ],
    "subjects": [ { "subject_id": "sub_...", "name": "Mug" } ],
    "location": { "subject_id": "sub_...", "name": "Terrace" }
  },
  "width": 1344, "height": 768, "seed": 42, "count": 1 }

• Najwyżej 4 obiekty (postacie, przedmioty i zwierzęta). Bez LoRA, tylko z obrazów: najwyżej 4 referencje, łącznie z miejscem. Serwer wybiera metodę na podstawie referencji i umieszcza każdą z nich w kolejności characters, a potem subjects, od lewej do prawej.
• @Nazwa, która nie wskazuje żadnej referencji, jest odrzucana (unknown_mention); referencja nieobecna w prompcie i tak zostaje wysłana.
• Cena: jeden przebieg kosztuje tyle co jeden obraz (1 kredyt). Prosty obraz to 1 przebieg; kilka postaci odgrywanych przez LoRA, 1 plus jeden przebieg na LoRA (najwyżej 4); tylko z obrazów, jeden przebieg na każdą referencję poza pierwszą; połączenie, jedno i drugie. Suma (przebiegi x count) jest rezerwowana przy przesłaniu i pobierana jeden raz, przy obrazie końcowym: niepowodzenie lub anulowanie nic nie kosztuje. POST /images/quote z tym samym ciałem żądania podaje dokładną cenę, metodę i jej przebiegi, niczego nie uruchamiając.
• Odpowiedź 202: { "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" } (przy count 2: jobs i cost_total). Odpytywanie, pobieranie i anulowanie korzystają ze zwykłych ścieżek opisanych niżej; podczas renderowania progress podaje bieżący przebieg ("2/3"). Obraz powstaje w 1 do 3 minut.
• Obraz końcowy pozostaje dostępny przez 1 godzinę, i przez 10 minut po pierwszym pobraniu. Nieudany przebieg daje status: "failed" z reason: "render_failed"; anulowanie, reason: "cancelled".
• Błędy: invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size, character_not_ready, a także błędy Multi-Ref (unknown_character, unknown_subject, unknown_lora, unknown_mention, multiref_too_many_references, invalid_strength...). Zobacz Limity i błędy.

Odpytywanie

GET /images/{jobId}

Odpytuj co 3 sekundy, nie częściej: kolejka jest współdzielona.

Pobieranie

GET /images/{jobId}/file

Sam plik PNG jako treść odpowiedzi (Content-Type: image/png). Dostępny od razu po uzyskaniu statusu completed, a 404 media_unavailable gdy render zostanie usunięty. Pobierz go od razu, nie jest archiwizowany.

Anulowanie

POST /images/{jobId}/cancel

Anuluje renderowanie w kolejce lub w trakcie. Odpowiada { "ok": true }. Nic nie jest naliczane, a koszt zarezerwowany na dzienny limit klucza jest zwracany.