Pro API: kuvien luonti ja retushointi
Yksi kuva maksaa 1 krediitti, tilasta riippumatta. Promptista luominen ja toimittamasi kuvan retushointi kulkevat saman reitin kautta.
POST /images/quote ottaa saman rungon ja palauttaa hinnan luomatta mitään, aina
{ "cost": 1, ... } tässä tapauksessa. Se on olemassa symmetrian vuoksi videoiden kanssa, joissa hinta vaihtelee.
Lähetä kuva
POST /images
{ "prompt": "portrait of a woman in a rainy street at night, neon reflections, cinematic",
"width": 832, "height": 1216 }| Kenttä | Tyyppi | Oletus | Mitä se tekee |
|---|---|---|---|
prompt | merkkijono | pakollinen | Kohtaus. Englanti antaa tarkimmat tulokset. |
width, height | int | 1024 x 1024 | Pikselikoko. Hyviä muotoja: 1024 x 1024 (neliö), 832 x 1216 (muotokuva), 1216 x 832 (maisema). |
mode | merkkijono | generation | edit, img2img tai inpaint, katso alla. Jos puuttuu, luodaan promptista. |
image_b64 | merkkijono | Lähdekuva base64-muodossa (PNG tai JPEG), pakollinen kaikissa kolmessa retusointitilassa. Enintään 12 MB purettuna. | |
mask_b64 | merkkijono | Peite base64-muodossa: pakollinen inpaint-tilassa, valinnainen edit-tilassa. Maalaa retushoitavat alueet punaisella lähdekuvan kokoisena. | |
lora | merkkijono | Tilillä oleva koulutettu hahmo: GET /loras -pyynnön palauttama name. Lisää sen trigger promptiin. | |
lora2, lora2_strength | merkkijono, numero | Toinen hahmo ja sen voimakkuus (0-1, oletus 1) kahden henkilön kohtaukseen. | |
count | int | 1 | Kuinka monta kuvaa tästä pyynnöstä renderöidään, 1-8. Jokaiselle arvotaan oma siemen; seed-kentän kanssa ne saavat arvot seed, seed+1, seed+2... Tämä vastaa sovelluksen Images per generation -valitsinta. |
seed | int | satunnainen | Renderöinnin siemen, välillä 0-4 294 967 295. Sama seed, sama prompt ja samat asetukset tuottavat saman renderöinnin, hyvin pienin eroin jos näytönohjain vaihtuu. seed-arvon säilyttäminen ja promptin muokkaaminen antaa muunnelman, joka pitää komposition. |
steps | int | moottori | Jätä tyhjäksi. Moottori tietää oman arvonsa. |
Vastaus:
{ "jobId": "test-79634842-4586-46d4-ad52-d9ea236ae00d", "seed": 178078967, "cost": 1 }seed palautetaan vastauksessa riippumatta siitä, antoitko sen itse vai arvottiinko se satunnaisesti: säilytä se renderöidäksesi saman kuvan uudelleen tai luodaksesi siitä muunnelman.
Usean kuvan pyytäminen kerralla
Kun count on yli 1, yksi pyyntö käynnistää useita renderöintejä, joista jokaisella on oma siemenensä, ja vastaus listaa ne:
{ "count": 4, "requested": 4, "cost_total": 4,
"jobs": [ { "jobId": "...", "seed": 178078967, "cost": 1 }, { "jobId": "...", "seed": 903412, "cost": 1 } ],
"errors": [],
"jobId": "...", "seed": 178078967, "cost": 1 }Kaksi asiaa, joihin kannattaa kiinnittää huomiota.
Ensimmäisen renderöinnin jobId, seed ja cost toistetaan ylimmällä tasolla. Se on siellä siksi, että ennen eräajoja kirjoitetut asiakasohjelmat toimivat muuttumattomina, ei siksi että ensimmäinen olisi tärkeämpi. Pollaa jokainen jobs-listan merkintä, ei vain sitä.
Vertaa count- ja requested-arvoja keskenään. Osittainen hylkäys krediittien puutteen tai avaimen päivittäisen katon saavuttamisen takia pysäyttää erän siihen pisteeseen: requested on pyytämäsi määrä, count on se, mikä oikeasti käynnistyi, ja errors kertoo syyn pysähtymiseen. Asiakasohjelma, joka olettaa niiden olevan yhtä suuret, menettää renderöintejä huomaamattaan.
POST /images/quote hyväksyy myös count-kentän ja hinnoittelee koko erän. Videoilla ei ole count-kenttää: yksi pyyntö, yksi klippi.
Kolme retusointitilaa
Kaikki kolme toimivat samalla ohjauspohjaisella muokkausmoottorilla, joka säilyttää lähdekuvan ulkonäön. Kun toimitat lähdekuvan, width ja height luetaan kuvasta itsestään eikä niitä tarvitse lähettää.
mode | Syötteet | Mitä moottori tekee |
|---|---|---|
edit | image_b64 + prompt (+ valinnainen mask_b64) | Soveltaa ohjeen koko kuvaan ("lisää aurinkolasit", "tee lumisade"). Peitteen kanssa muutos kohdistuu punaiselle alueelle. |
inpaint | image_b64 + mask_b64 + prompt | Regeneroi vain peitteen punaisen alueen ohjeen mukaisesti. Muu osa koostetaan piksel kerrallaan. |
img2img | image_b64 + prompt | Työstää koko kuvan promptin mukaisesti säilyttäen sen komposition ja ulkonäön: muunnelma. |
Tilassa edit palvelin valitsee itse parhaan tavan käsitellä muokkauksen, kuten sovellus:
- maskin kanssa: se lukee ohjeen ja valitsee, korvataanko alueen sisältö (toinen esine, toinen vaate, kasvot: alue piirretään uudelleen sen mukaan, mitä siinä pitää näkyä) vai muutetaanko sitä, mitä siinä on (väri, materiaali, valo). Hahmon
lora:n kanssa alue piirretään aina uudelleen, kasvot mukaan lukien; - ilman maskia, hahmon
lora:n kanssa ("replace the woman with kara..."): palvelin löytää kuvan henkilön ja piirtää hänet uudelleen hahmona; jos ketään ei löydy, ohje koskee koko kuvaa, kuten ennenkin.
Sama hinta kaikissa tapauksissa (1 krediitti kuvaa kohden). Valinta näkyy tuloksessa, ei vastauksessa.
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\"}"Luo kuva hahmoilla, esineillä ja sijainnilla
Lisää multiref-objekti POST /images -pyyntöön, niin palvelin tuo hahmosi (Hahmot), esineesi ja eläimesi sekä sijainnin (Kohteet) yhdessä samaan kuvaan, jokaisen tunnistettavana, kuten sovelluksen "Create an image" -ruutu. Kutsu jokaista @Nimi-muodolla promptissa, englanniksi.
{ "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 }multiref-kentät | Mitä tekee |
|---|---|
characters[].character_id, name | Hahmo reitiltä GET /characters; name on sana, joka kirjoitetaan @-merkin jälkeen (kirjaimet, numerot, _). |
characters[].view | Sen character sheetin näkymä, joka edustaa hahmoa, 1-5 (oletuksena 1, rintakuva edestä). |
characters[].sheet_id | Valinnainen: käytettävä character sheet (oletuksena uusin). |
characters[].lora | Valinnainen: hahmon oma kuva-LoRA, nimi GET /loras -vastauksen image-listasta. Hahmoa esittää silloin sen LoRA, ei sen näkymä. |
characters[].strength | LoRA:n voimakkuus, 0-1,5 (oletuksena 1). |
characters[].lora_pass | Osuus kuvasta, jonka hahmon LoRA-kierros maalaa uudelleen, 0,3-0,9 (oletuksena 0,55); hyödyllinen, kun kohteita on useita. |
characters[].description | Valinnainen, englanniksi: asu, ikä... |
subjects[] | Esineet ja eläimet reitiltä /subjects: subject_id, name (oletuksena sen nimen ensimmäinen sana), description, image (mikä sen kuvista, oletuksena 1). |
location | Sijainti reitiltä /subjects (subject_id, name) tai kertakäyttöinen tausta: background_b64 ja background_description. |
count | 1 tai 2: kuvat renderöidään peräkkäin. |
- Enintään 4 kohdetta (hahmot, esineet ja eläimet). Ilman LoRA:a, pelkistä kuvista: enintään 4 viitettä, sijainti mukaan lukien. Palvelin valitsee menetelmän viitteiden perusteella ja sijoittaa jokaisen järjestyksessä ensin
characters, sittensubjects, vasemmalta oikealle. @Nimi, joka ei vastaa mitään viitettä, hylätään (unknown_mention); promptista puuttuva viite lähetetään silti.- Hinta: yksi kierros maksaa yhden kuvan hinnan (1 krediitti). Yksinkertainen kuva on 1 kierros; useampi LoRA:n esittämä hahmo, 1 sekä yksi kierros kutakin LoRA:a kohti (enintään 4); pelkistä kuvista yksi kierros jokaista ensimmäisen jälkeistä viitettä kohti; yhdistelmä, molemmat. Kokonaissumma (kierrokset x
count) varataan lähetettäessä ja veloitetaan kerran, lopullisen kuvan kohdalla: epäonnistuminen tai peruutus ei maksa mitään.POST /images/quotesamalla rungolla antaa tarkan hinnan, menetelmän ja sen kierrokset käynnistämättä mitään. - Vastaus
202:{ "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" }(kuncounton 2:jobsjacost_total). Pollaus, lataus ja peruutus käyttävät alla olevia tavallisia reittejä; renderöinnin aikanaprogresskertoo käynnissä olevan kierroksen ("2/3"). Kuva vie 1-3 minuuttia. - Lopullinen kuva on saatavilla 1 tunnin ajan, ja 10 minuuttia ensimmäisen latauksensa jälkeen. Epäonnistunut kierros antaa
status: "failed"jareason: "render_failed"; peruutus,reason: "cancelled". - Virheet:
invalid_count,invalid_view,invalid_lora_pass,invalid_subject_image,invalid_size,character_not_readysekä Multi-Ref-virheet (unknown_character,unknown_subject,unknown_lora,unknown_mention,multiref_too_many_references,invalid_strength...). Katso Rajat ja virheet.
Pollaus
GET /images/{jobId}
| Vastaus | Merkitys |
|---|---|
{ "status": "pending", "phase": "IN_QUEUE" } | Jonossa |
{ "status": "pending", "phase": "IN_PROGRESS" } | Renderöidään |
{ "status": "completed", "cost": 1, "file_url": "/pro/v1/images/{jobId}/file", ... } | Valmis, tiedosto saatavilla |
{ "status": "failed", "detail": "..." } | Epäonnistui, eikä mitään veloiteta |
Pollaa 3 sekunnin välein, ei tiheämmin: jono on jaettu.
Lataus
GET /images/{jobId}/file
PNG-tiedosto itse vastaustekstinä (Content-Type: image/png). Saatavilla heti kun tila on completed, ja 404 media_unavailable kun renderöinti on poistunut. Lataa se heti, sitä ei arkistoida.
Peruutus
POST /images/{jobId}/cancel
Peruuttaa jonossa olevan tai käynnissä olevan renderöinnin. Palauttaa { "ok": true }. Mitään ei veloiteta, ja avaimen päivittäiselle katolla varattu kustannus palautetaan.