Pro API: afbeeldingen genereren en bewerken
Één afbeelding kost 1 credit, ongeacht de modus. Genereren vanuit een prompt en het bewerken van een afbeelding die je zelf aanlevert verlopen allebei via dezelfde route.
POST /images/quote neemt dezelfde body en geeft de prijs terug zonder iets aan te maken, altijd
{ "cost": 1, ... } hier. Dit bestaat voor symmetrie met video's, waarbij de prijs wel varieert.
Een afbeelding indienen
POST /images
{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
"width": 832, "height": 1216 }| Veld | Type | Standaard | Wat het doet |
|---|---|---|---|
prompt | string | verplicht | De scène. Engels geeft de meest precieze resultaten. |
width, height | int | 1024 x 1024 | Pixelgrootte. Goede verhoudingen: 1024 x 1024 (vierkant), 832 x 1216 (staand), 1216 x 832 (liggend). |
mode | string | generation | edit, img2img of inpaint, zie hieronder. Afwezig betekent genereren vanuit de prompt. |
image_b64 | string | Bronafbeelding in base64 (PNG of JPEG), verplicht bij alle drie de bewerkingsmodi. Maximaal 12 MB gedecodeerd. | |
mask_b64 | string | Masker in base64: verplicht bij inpaint, optioneel bij edit. Teken de te bewerken gebieden rood in, op het formaat van de bronafbeelding. | |
lora | string | Een getraind personage op het account: de name die wordt teruggegeven door GET /loras. Zet de trigger ervan in de prompt. | |
lora2, lora2_strength | string, number | Een tweede personage en diens sterkte (0 tot 1, standaard 1) voor een scène met twee personen. | |
count | int | 1 | Hoeveel afbeeldingen er van dit ene verzoek worden gegenereerd, 1 tot 8. Elk krijgt zijn eigen verse seed; met seed nemen ze seed, seed+1, seed+2... Dit is de Afbeeldingen per generatie-selector van de app. |
seed | int | willekeurig | Seed van de render, van 0 tot 4294967295. Dezelfde seed, dezelfde prompt en dezelfde instellingen geven dezelfde render, met zeer kleine verschillen als de grafische kaart verandert. De seed bewaren en de prompt aanpassen geeft een variatie die de compositie behoudt. |
steps | int | engine | Leeg laten. De engine kent zijn eigen waarde. |
Het antwoord:
{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }De seed wordt in het antwoord teruggegeven, of je die nu zelf opgaf of dat die willekeurig werd gekozen: bewaar hem om
dezelfde afbeelding opnieuw te renderen, of een variatie daarvan.
Meerdere tegelijk opvragen
Met count hoger dan 1 start één verzoek meerdere renders, elk met hun eigen seed, en het
antwoord somt ze op:
{ "count": 4, "requested": 4, "cost_total": 4,
"jobs": [ { "jobId": "...", "seed": 178078967, "cost": 1 }, { "jobId": "...", "seed": 903412, "cost": 1 } ],
"errors": [],
"jobId": "...", "seed": 178078967, "cost": 1 }Twee dingen om goed op te letten.
De jobId, seed en cost van de eerste render worden op het hoogste niveau herhaald. Dat is
er om clients die geschreven zijn vóór batches ongewijzigd te laten werken, niet omdat de eerste belangrijker is. Poll elke invoer van jobs, niet alleen die ene.
En vergelijk count met requested. Een weigering halverwege, wegens gebrek aan credits of
omdat de sleutel zijn dagelijkse limiet heeft bereikt, stopt de batch waar hij is: requested is wat je hebt gevraagd,
count is wat er daadwerkelijk is gestart, en errors legt uit waarom het is gestopt. Een client die ervan uitgaat
dat de twee gelijk zijn, verliest stilletjes renders.
POST /images/quote neemt count ook mee en berekent de prijs voor de hele batch. Video's hebben geen count:
één verzoek, één clip.
De drie bewerkingsmodi
Alle drie draaien op dezelfde instructiegestuurde bewerkingsengine, die het uiterlijk van de
bronafbeelding behoudt. Wanneer je een bronafbeelding meegeeft, worden width en height uit de afbeelding zelf gelezen en hoeven ze niet te worden meegestuurd.
mode | Invoer | Wat de engine doet |
|---|---|---|
edit | image_b64 + prompt (+ optioneel mask_b64) | Past de instructie toe op de hele afbeelding ("add sunglasses", "make it snow"). Met een masker concentreert de wijziging zich binnen het rode gebied. |
inpaint | image_b64 + mask_b64 + prompt | Regenereert alleen het rode gebied van het masker, op basis van de instructie. De rest wordt pixel voor pixel gereconstrueerd. |
img2img | image_b64 + prompt | Bewerkt de hele afbeelding op basis van de prompt terwijl de compositie en het uiterlijk bewaard blijven: een variatie. |
Bij edit kiest de server zelf de beste manier om de bewerking aan te pakken, zoals de app:
- met een masker: hij leest de instructie en kiest tussen vervangen wat de zone bevat (een ander object, een ander kledingstuk, een gezicht: de zone wordt opnieuw getekend naar wat er moet verschijnen) en wijzigen wat er staat (kleur, materiaal, licht). Met een personage-
lorawordt de zone altijd opnieuw getekend, gezicht inbegrepen; - zonder masker, met een personage-
lora("replace the woman with kara..."): de server vindt de persoon op de foto en tekent die opnieuw als het personage; vindt hij niemand, dan geldt de instructie zoals voorheen voor de hele afbeelding.
Dezelfde prijs in elk geval (1 credit per afbeelding). De keuze zie je in het resultaat, niet in het antwoord.
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\"}"Een afbeelding maken met personages, objecten en een locatie
Voeg een multiref-object toe aan POST /images en de server laat je personages (Personages), je objecten en dieren en een locatie (Onderwerpen) samen spelen in één afbeelding, elk herkenbaar, zoals het scherm "Afbeelding maken" van de app. Roep elk ervan op via @Naam in de prompt, in het Engels.
{ "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 }Veld van multiref | Wat het doet |
|---|---|
characters[].character_id, name | Een personage uit GET /characters; name is het woord dat na @ wordt geschreven (letters, cijfers, _). |
characters[].view | De weergave van zijn sheet die het personage vertegenwoordigt, 1 tot 5 (standaard 1, de buste vooraanzicht). |
characters[].sheet_id | Optioneel: de sheet die wordt gebruikt (standaard de meest recente). |
characters[].lora | Optioneel: zijn afbeeldings-LoRA, een naam uit de lijst image van GET /loras. Het personage wordt dan gespeeld door zijn LoRA, niet door zijn weergave. |
characters[].strength | Sterkte van de LoRA, 0 tot 1,5 (standaard 1). |
characters[].lora_pass | Deel van de afbeelding dat zijn LoRA-pass opnieuw schildert, 0,3 tot 0,9 (standaard 0,55); handig met meerdere onderwerpen. |
characters[].description | Optioneel, in het Engels: outfit, leeftijd... |
subjects[] | Objecten en dieren uit /subjects: subject_id, name (standaard het eerste woord van zijn naam), description, image (welke van zijn afbeeldingen, standaard 1). |
location | Een locatie uit /subjects (subject_id, name), of een eenmalige achtergrond: background_b64 en background_description. |
count | 1 of 2: de afbeeldingen worden na elkaar gerenderd. |
- Maximaal 4 onderwerpen (personages, objecten en dieren). Zonder LoRA, alleen vanuit afbeeldingen: maximaal 4 referenties, de locatie inbegrepen. De server kiest de methode op basis van de referenties, en plaatst elk ervan in de volgorde van
charactersen dansubjects, van links naar rechts. - Een
@Naamdie bij geen enkele referentie hoort, wordt geweigerd (unknown_mention); een referentie die niet in de prompt staat, wordt toch meegestuurd. - Prijs: één pass kost de prijs van één afbeelding (1 credit). Een eenvoudige afbeelding is 1 pass; meerdere personages gespeeld door een LoRA, 1 plus één pass per LoRA (maximaal 4); alleen vanuit afbeeldingen, één pass per referentie na de eerste; een combinatie, allebei. Het totaal (passes x
count) wordt bij het indienen gereserveerd en één keer afgeschreven, bij de uiteindelijke afbeelding: een mislukking of een annulering kost niets.POST /images/quotemet dezelfde body geeft de exacte prijs, de methode en de passes ervan, zonder iets te starten. - Antwoord
202:{ "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" }(metcount2:jobsencost_total). Pollen, downloaden en annuleren verlopen via de gebruikelijke routes hieronder; tijdens het renderen geeftprogressde huidige pass ("2/3"). Een afbeelding duurt 1 tot 3 minuten. - De uiteindelijke afbeelding blijft 1 uur beschikbaar, en 10 minuten na de eerste download. Een mislukte pass geeft
status: "failed"metreason: "render_failed"; een annulering,reason: "cancelled". - Fouten:
invalid_count,invalid_view,invalid_lora_pass,invalid_subject_image,invalid_size,character_not_ready, plus die van Multi-Ref (unknown_character,unknown_subject,unknown_lora,unknown_mention,multiref_too_many_references,invalid_strength...). Zie Limieten en fouten.
Polling
GET /images/{jobId}
| Antwoord | Betekenis |
|---|---|
{ "status": "pending", "phase": "IN_QUEUE" } | In de wachtrij |
{ "status": "pending", "phase": "IN_PROGRESS" } | Aan het renderen |
{ "status": "completed", "cost": 1, "file_url": "/pro/v1/images/{jobId}/file", ... } | Klaar, bestand beschikbaar |
{ "status": "failed", "detail": "..." } | Mislukt, en er wordt niets in rekening gebracht |
Poll elke 3 seconden, niet vaker: de wachtrij is gedeeld.
Downloaden
GET /images/{jobId}/file
De PNG zelf, als de responsebody (Content-Type: image/png). Beschikbaar zodra de
status completed is, en 404 media_unavailable zodra de render is verdwenen. Download hem meteen, hij wordt niet gearchiveerd.
Annuleren
POST /images/{jobId}/cancel
Annuleert een render die in de wachtrij staat of actief is. Geeft { "ok": true } terug. Er wordt niets in rekening gebracht, en de kosten die zijn gereserveerd voor de dagelijkse limiet van de sleutel worden teruggegeven.