Pro API: generera och retuschera bilder

En bild kostar 1 kredit, oavsett läge. Generering från en prompt och retuschering av en bild du tillhandahåller går båda genom samma rutt.

POST /images/quote tar samma body och svarar med priset utan att skapa något, alltid { "cost": 1, ... } här. Det finns för symmetrins skull med videor, där priset faktiskt varierar.

Skicka en bild

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 returneras i svaret, oavsett om du angav det eller om det drogs slumpmässigt: spara det för att rendera samma bild igen, eller en variation av den.

Be om flera på en gång

Med count över 1 startar en förfrågan flera renderingar, var och en med sitt eget seed, och svaret listar 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 }

Två saker att läsa noggrant.

jobId, seed och cost för den första renderingen upprepas på toppnivån. Det finns där för att klienter skrivna innan batcher stöds ska fortsätta fungera oförändrat, inte för att den första spelar större roll. Polla varje post i jobs, inte bara den.

Och jämför count med requested. Ett avvisande mitt i processen, på grund av brist på krediter eller för att nyckeln nådde sitt dagliga tak, stoppar batchen där den är: requested är vad du bad om, count är vad som faktiskt startade, och errors förklarar varför det stannade. En klient som antar att de två är lika tappar tyst renderingar.

POST /images/quote tar count också och prissätter hela batchen. Videor har ingen count: en förfrågan, ett klipp.

De tre retuscheringslägena

Alla tre körs på samma instruktionsdrivna redigeringsmotor, som bevarar källbildens utseende. När du tillhandahåller en källbild läses width och height från bilden själv och behöver inte skickas med.

I edit väljer servern själv det bästa sättet att hantera redigeringen, som appen:

• med en mask: den läser instruktionen och väljer mellan att ersätta det som finns i området (ett annat föremål, ett annat plagg, ett ansikte: området ritas om efter det som ska synas där) och att ändra det som finns där (färg, material, ljus). Med en karaktärs-lora ritas området alltid om, ansiktet inräknat;
• utan mask, med en karaktärs-lora ("replace the woman with kara..."): servern hittar personen på fotot och ritar om den som karaktären; hittar den ingen gäller instruktionen hela bilden, som tidigare.

Samma pris i alla fall (1 kredit per bild). Valet syns i resultatet, inte 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\"}"

Skapa en bild med karaktärer, objekt och en plats

Lägg till ett multiref-objekt i POST /images så låter servern dina karaktärer (Karaktärer), dina objekt och djur och en plats (Subjekt) spela tillsammans i en enda bild, var och en igenkännbar, som appens "Create an image"-skärm. Anropa var och en med @Namn i prompten, på engelska.

{ "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ögst 4 subjekt (karaktärer, objekt och djur). Utan LoRA, enbart från bilder: högst 4 referenser, platsen inräknad. Servern väljer metoden utifrån referenserna och placerar var och en i ordningen characters och sedan subjects, från vänster till höger.
• Ett @Namn som inte matchar någon referens nekas (unknown_mention); en referens som saknas i prompten skickas ändå med.
• Pris: en omgång kostar priset för en bild (1 kredit). En enkel bild är 1 omgång; flera karaktärer som spelas av en LoRA, 1 plus en omgång per LoRA (högst 4); enbart från bilder, en omgång per referens utöver den första; en blandning, båda. Totalen (omgångar x count) reserveras när förfrågan skickas och debiteras en enda gång, vid den slutliga bilden: ett misslyckande eller ett avbrott kostar ingenting. POST /images/quote med samma body ger det exakta priset, metoden och dess omgångar, utan att starta något.
• Svar 202: { "jobId": "mri_...", "seed", "cost", "method", "passes", "billed_passes" } (med count 2: jobs och cost_total). Polling, nedladdning och avbrytning går via de vanliga rutterna nedan; under renderingen anger progress den pågående omgången ("2/3"). En bild tar 1 till 3 minuter.
• Den slutliga bilden förblir tillgänglig i 1 timme, och 10 minuter efter sin första nedladdning. En misslyckad omgång ger status: "failed" med reason: "render_failed"; ett avbrott, reason: "cancelled".
• Fel: invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size, character_not_ready, samt de från Multi-Ref (unknown_character, unknown_subject, unknown_lora, unknown_mention, multiref_too_many_references, invalid_strength...). Se Begränsningar och fel.

Polla

GET /images/{jobId}

Polla var 3:e sekund, inte snabbare: kön är delad.

Ladda ned

GET /images/{jobId}/file

PNG-filen i sig, som svarskropp (Content-Type: image/png). Tillgänglig så snart statusen är completed, och 404 media_unavailable när renderingen är borta. Ladda ned den direkt, den arkiveras inte.

Avbryt

POST /images/{jobId}/cancel

Avbryter en köad eller pågående rendering. Svarar { "ok": true }. Inget debiteras, och kostnaden reserverad mot nyckelns dagliga tak återbetalas.