API reference

Image studio (company keys)

Make an image from a prompt, or change your own photo, with the Nano Banana 2 model at 512 × 512 pixels. For companies that bought the Image studio: every image comes out of an image pack you bought once.

Generate an image

Send a JSON body with a prompt and, to edit your own photo, one or more reference images. The reply holds the image as base64 and what is left in your pack.

curl https://acacus.ly/v1/studio/images/generate \
  -H "Authorization: Bearer $ACACUS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "prompt": "The same bag on a clean white background, soft shadow",
    "reference_images": ["data:image/jpeg;base64,'"$(base64 -w0 bag.jpg)"'"]
  }'

The reply (the image is shortened here; this reply was written from the code, not captured from a live run):

{
  "created": 1790380421,
  "model": "nano-banana-2",
  "size": "512x512",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUg...", "mime_type": "image/png" }
  ],
  "pack": { "id": "imgpack_9c1f4e0a7d3b58a2c6e41f90", "remaining": 4812, "expiresAt": "2027-04-01T09:00:00.000Z" },
  "usage": { "images": 1, "requested_images": 1, "prompt_tokens": 14, "reference_images": 1, "extra_charge_lyd": 0 }
}

Request body

Editing your own photo and making a new image cost the same. There is no model field: the model is the Nano Banana 2 model, and a model you send is ignored.

Your image pack

Images come from packs you bought once, not from a subscription: 1,000 images, 5,000 images, 10,000 images, 20,000 images, 35,000 images, each as an instant pack or a 24-hour batch pack. Images stay usable for 6 months from the purchase date. When a pack runs out or expires, requests stop with 402 PACK_EMPTY until you buy a new one; the images are never taken from your wallet. This endpoint draws from your instant packs, the one that expires first. Every reply says which pack was used and how many images it has left (the pack object), and the console shows all your packs.

An image is used only when it is delivered. If the image model fails, answers without an image or declines the request, or you disconnect before the answer, the image goes back to the pack and nothing is charged.

Fair use

The pack price includes a prompt of up to 2,000 tokens and one reference image for each image you make. Beyond that, a small amount is charged from your wallet (the balance you also use for the chat API), for each image:

A request needs its extra in your wallet before it starts: if the balance cannot cover it, the request is refused with 402 INSUFFICIENT_BALANCE_EXTRA and nothing is used from your pack. The extra counts toward your company's monthly cap in LYD; the images themselves do not. Prompt tokens are counted by Acacus (an estimate, rounded up to whole thousands for the charge). These numbers can change; the reply's usage.extra_charge_lyd says what was charged.

Limits

Repeating a request safely

Send an Idempotency-Key header (up to 128 characters: letters, digits and _ . : -). A request repeated with the same key is one charge. The key is bound to the first request sent with it: a repeat gets the first reply back whatever its body says, so use a new key for a different request.

The images of a finished reply are kept for 15 minutes so that a retry can return them, and then deleted. Acacus keeps no prompt and no image otherwise, only the counts and the cost.

Errors

Errors come in the same shape as the rest of the API:

{
  "error": {
    "message": "Your image pack is empty or has expired: 0 images remain. Buy a new pack from Shafra to keep generating. Nothing was charged to your wallet.",
    "type": "insufficient_quota",
    "code": "PACK_EMPTY",
    "param": null,
    "remaining": 0
  }
}

More on the format, and which errors to retry, in Errors.

24-hour batch

Batch delivery (images within 24 hours, at the batch pack price) is not built yet. This path answers 501 BATCH_NOT_READY. Use the instant endpoint above with an instant pack. We will announce batch delivery in the changelog when it opens.