Skip to content
Log in
Developer API
Get your keyGet a key

Get started

Credits, quotes and confirming a price

The API spends your Vessero credits at the prices the site shows. Nothing runs until your call names the price.

Price it · freePOST/images/quote
curl -X POST https://vessero.com/api/v1/images/quote \
  -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"
    ]
  }'
Response200 OK
{
  "object": "quote",
  "credits": 12,
  "balance": 840,
  "lines": [
    "1 image × 12 (Nano Banana Pro · 4K)"
  ],
  "notes": [],
  "requestId": "47f8f6f5-ea00-4fb1-925f-76aac956a0ec",
  "run": {
    "method": "POST",
    "path": "/api/v1/images",
    "confirmCredits": 12,
    "idempotencyKey": "47f8f6f5-ea00-4fb1-925f-76aac956a0ec"
  }
}
Response409 Conflict
{
  "error": {
    "code": "price_changed",
    "message": "Nothing was run or charged: the price is now 14 credits, not the 12 confirmed.",
    "retryable": false,
    "requestId": "req_7Lq2XbN0vT4mKc9P",
    "details": {
      "quote": {
        "object": "quote",
        "credits": 14,
        "balance": 840,
        "lines": [
          "1 image × 12 (Nano Banana Pro · 4K)"
        ],
        "notes": [],
        "requestId": "47f8f6f5-ea00-4fb1-925f-76aac956a0ec",
        "run": {
          "method": "POST",
          "path": "/api/v1/images",
          "confirmCredits": 12,
          "idempotencyKey": "47f8f6f5-ea00-4fb1-925f-76aac956a0ec"
        }
      }
    }
  }
}

Price it first

Every address that spends has a twin ending in /quote that takes the same body: POST /images/quote prices POST /images. It answers the price in credits, your balance, the price line by line, and any notes the studio’s page would show. It runs nothing and costs nothing.

Run it at that price

Send the same body to the address itself with confirmCredits set to the price, and the run starts, charged that price.

  • Leave confirmCredits out, and nothing runs: the answer is 400 confirm_credits_required, with the quote in details.
  • If the price has gone up since you asked, nothing runs: 409 price_changed, with the new quote.
  • If it has come down, the run goes ahead at the lower price, as long as your confirmCredits is the figure quoted for the same Idempotency-Key.
  • If your balance is too low, nothing runs: 402 insufficient_credits.
  • If the key’s daily cap would be passed, nothing runs: 429 daily_cap_reached, open again at midnight UTC.

The Creative Director

A message to the Creative Director is priced the same way: POST /director/messages/quote answers the most the reply’s first step holds, and it is settled to what the reply used. What the director proposes to make comes back as a batch, made only when you approve it with confirmCredits set to its totalCredits.

When a run fails

Most runs that fail are not charged: the credits go back, as they do on the site. A failed job says whether it was charged.