Pro API: generer og retoucher billeder

Et billede koster 1 kredit, uanset tilstand. Generering fra en prompt og retouchering af et billede, du selv leverer, går begge gennem den samme rute.

POST /images/quote tager samme body og returnerer prisen uden at oprette noget, altid { "cost": 1, ... } her. Den findes for symmetriens skyld med videoer, hvor prisen varierer.

Send et billede

POST /images

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

Svaret:

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

seed returneres i svaret, uanset om du angav det, eller det blev trukket tilfældigt: gem det for at rendere det samme billede igen eller en variation af det.

Anmode om flere på én gang

Med count over 1 starter én anmodning flere renderinger, hver med sit eget seed, og svaret lister dem:

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

To ting du skal læse nøje.

jobId, seed og cost for den første rendering gentages på øverste niveau. Det er der for at klienter skrevet før batch-understøttelse fortsat fungerer uændret, ikke fordi den første er vigtigere. Poll hvert element i jobs, ikke kun det ene.

Og sammenlign count med requested. En afvisning undervejs, på grund af manglende kreditter eller fordi nøglen har nået sit daglige loft, stopper batchen, hvor den er: requested er det, du bad om, count er det, der rent faktisk startede, og errors fortæller, hvorfor det stoppede. En klient, der antager, at de to er ens, mister lydløst renderinger.

POST /images/quote tager count med, og prissætter hele batchen. Videoer har ingen count: én anmodning, ét klip.

De tre retoucheringstilstande

Alle tre kører på den samme instruktionsdrevne redigeringsmotor, som bevarer udseendet af kildebilledet. Når du leverer et kildebillede, læses width og height fra billedet selv og behøver ikke sendes med.

I edit vælger serveren selv den bedste måde at håndtere redigeringen på, som appen:

• med en maske: den læser instruktionen og vælger mellem at erstatte indholdet i området (et andet objekt, et andet stykke tøj, et ansigt: området tegnes igen ud fra det, der skal vises der) og at ændre det, der er der (farve, materiale, lys). Med en karakter-lora tegnes området altid igen, ansigtet medregnet;
• uden maske, med en karakter-lora ("replace the woman with kara..."): serveren finder personen på billedet og tegner vedkommende igen som karakteren; finder den ingen, gælder instruktionen hele billedet, som før.

Samme pris i alle tilfælde (1 kredit pr. billede). Valget ses i resultatet, ikke i svaret.

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\"}"

Lav et billede med karakterer, objekter og en lokation

Tilføj et multiref-objekt til POST /images, så lader serveren dine karakterer (Karakterer), dine objekter og dyr og en lokation (Subjects) spille sammen i ét enkelt billede, hver enkelt genkendelig, ligesom appens "Create an image"-skærm. Kald hver af dem med @Navn i prompten, på engelsk.

{ "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 }

• Højst 4 subjects (karakterer, objekter og dyr). Uden LoRA, kun ud fra billeder: højst 4 referencer, lokationen medregnet. Serveren vælger metoden ud fra referencerne og placerer hver enkelt i rækkefølgen characters og derefter subjects, fra venstre mod højre.
• Et @Navn, der ikke matcher nogen reference, afvises (unknown_mention); en reference, der mangler i prompten, sendes alligevel med.
• Pris: ét gennemløb koster prisen for ét billede (1 kredit). Et simpelt billede er 1 gennemløb; flere karakterer spillet af en LoRA, 1 plus ét gennemløb pr. LoRA (højst 4); kun ud fra billeder, ét gennemløb pr. reference ud over den første; en blanding, begge dele. Totalen (gennemløb x count) reserveres ved indsendelsen og opkræves én gang, ved det endelige billede: en fejl eller en annullering koster intet. POST /images/quote med samme body giver den præcise pris, metoden og dens gennemløb, uden at starte noget.
• Svar 202: { "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" } (med count 2: jobs og cost_total). Polling, download og annullering bruger de sædvanlige ruter nedenfor; under renderingen angiver progress det igangværende gennemløb ("2/3"). Et billede tager 1 til 3 minutter.
• Det endelige billede forbliver tilgængeligt i 1 time, og 10 minutter efter den første download. Et mislykket gennemløb giver status: "failed" med reason: "render_failed"; en annullering, reason: "cancelled".
• Fejl: invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size, character_not_ready, plus dem fra Multi-Ref (unknown_character, unknown_subject, unknown_lora, unknown_mention, multiref_too_many_references, invalid_strength...). Se Grænser og fejl.

Poll

GET /images/{jobId}

Poll hvert 3. sekund, ikke hurtigere: køen er delt.

Download

GET /images/{jobId}/file

Selve PNG-filen som response body (Content-Type: image/png). Tilgængelig så snart status er completed, og 404 media_unavailable når renderingen er slettet. Download den med det samme, den arkiveres ikke.

Annuller

POST /images/{jobId}/cancel

Annullerer en rendering i kø eller i gang. Svarer { "ok": true }. Intet opkræves, og omkostningen reserveret mod nøglens daglige loft tilbagebetales.