Make pictures from words and reference pictures

Make one picture from words, and from pictures of the person’s own where the model takes them (an edit, a product put in a new scene, a face kept): the Images page’s run. Pick the model and its options with GET /api/v1/models (studio "images"): its shapes, sizes, how many pictures it reads and, on Soul, its styles, seed and polish. Pictures go in as storage keys or https links. The picture comes back in the call once made: a link (good for about 7 days) and its id, which POST /api/v1/library/use turns into a key for other create tools. One from a slow model (Midjourney’s often take two to five minutes), still being made after about 45 seconds, comes back as a job instead: follow it with GET /api/v1/jobs/{jobId} (kind "image"), which gives its links once done. One picture a call — except a model whose picturesPerRun is more than one (Midjourney makes four, all for the one price), which returns them all; for more, call once each with a new Idempotency-Key.

Key needs: create · Make things and spend credits
Price it first: POST /images/quote · free
Answers: What it made, at once

Request

curl -X POST https://vessero.com/api/v1/images \
  -H "Authorization: Bearer $VESSERO_API_KEY" \
  -H "Idempotency-Key: 47f8f6f5-ea00-4fb1-925f-76aac956a0ec" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The shirt in the picture on a wooden hanger by a window, soft morning light",
    "model": "nano-banana-pro",
    "resolution": "4K",
    "referenceKeys": [
      "https://example.com/products/linen-shirt.jpg"
    ],
    "confirmCredits": 12
  }'

Response200 OK

{
  "status": "done",
  "pictures": [
    {
      "id": "9897acf1-abd2-470c-b0b6-7c0002ff3805",
      "url": "https://vessero.com/f/hSnRITVg9pUShOfHWU0DbIAn",
      "madeWith": "Nano Banana Pro · 4K",
      "useAs": {
        "kind": "library",
        "source": "studio",
        "id": "9897acf1-abd2-470c-b0b6-7c0002ff3805"
      }
    }
  ],
  "credits": 12
}

POST/images/quoteFree

The same body without confirmCredits. It answers the price and your balance, and runs nothing.

Header

Idempotency-KeystringYour id for this request: 8–64 letters, digits, - or _. A repeat within 10 minutes gets the first answer back and never runs twice. Use the same one for the quote and the run.
Preferstringwait=N (up to 60): hold the answer up to N seconds while the job is made, within 80 seconds for the whole call.

Body

promptstringrequiredWhat the picture shows, e.g. "A linen shirt on a wooden hanger by a window, soft morning light".
modelstringA picture model id from GET /api/v1/models (studio "images"), e.g. "nano-banana-pro". Default: the Images page’s own.
aspectRatiostringA shape the model lists (its aspectRatios), e.g. "16:9". Default: the model’s own.
resolutionstringA size the model lists (its resolutions), e.g. "2K" — or, where its resolutionsAre says "Speed", a speed: Midjourney’s "Fast" or "Turbo". Default: the model’s own.
referenceKeysstring[] · up to 16Pictures to work from, up to the model’s maxPictures. A model that needs a picture (needsPicture) makes nothing without one.
negativePromptstringWhat to leave out of the picture, for a model that takes it (takesNegativePrompt).
styleIdstringA style, on a model with a list of them (styles in GET /api/v1/models, studio "images": Soul): one of its styles.choices ids. Default: none, the model’s own look. Never moves the price.
styleStrengthnumberHow strongly the style is applied, 0–1, on a model that takes it (styles.strength), with a styleId. Default: auto.
seedintegerA seed, 1–1,000,000, on a model that takes one (seed "optional"): the same seed and settings make the same picture again. Default: a new one each run.
polishPromptboolean"Polish my words", on a model that has it (polish "optional"): the model rewrites the prompt into a fuller one before it runs; polishWithPicture says what it does with a picture in. Default: off.
confirmCreditsintegerrequiredThe price you agree to, in credits: the credits its quote gave. It runs at that price, or at a lower one when that figure was quoted for this Idempotency-Key; above the price now, nothing runs (409 price_changed). Left out, nothing runs and the error carries the quote.
webhookUrlstring · httpsAn https address to POST the job to once it is done or has failed, signed (see Webhooks).

Answers

200madeMade: the pictures, each with its link (good for about 7 days) and its id.
400confirm_credits_requiredA run that spends needs confirmCredits: the quote is in details.
402insufficient_creditsThe account has too few credits for this.
409price_changedThe price is above the confirmCredits sent: nothing ran; the new quote is in details.
422content_refusedThe content check refused it.
429daily_cap_reachedThe key’s daily credit cap would be passed: see Retry-After.

Next in ImagesPOST/images/quotePrice it: make pictures from words and reference pictures