Guide: generate and edit images

Create images from text, edit photos with reference images, and use the background, upscale and cleanup tools — with model choices and costs.

Images are the fastest and cheapest thing to generate, which makes them the best place to learn the API. Most image models finish in under a minute, so you can use ?wait=60 and get the picture back in the same response.

Text to image

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask?wait=60" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "black-forest-labs/flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "Product photo of a ceramic coffee mug on a linen tablecloth, soft window light, shallow depth of field",
      "aspect_ratio": "4:3"
    }
  }'

The result is in data.output.assets[0].url. If the response is a 202 instead, the model needed more than 60 seconds; read the task with recordInfo.

Which model

You want	Try	Why
The quickest, cheapest drafts	`alibaba/z-image-turbo/text-to-image`	About ten seconds and a couple of credits per image
Good all-round quality at a low price	`black-forest-labs/flux-2-klein-9b/text-to-image`	Fast, sharp, follows prompts well
Readable text, posters, diagrams	`google/nano-banana-2.1/text-to-image`, `openai/gpt-image-2/text-to-image`	Strong at lettering and layout; up to 4K
Several options in one call	Models with `num_outputs`	One task, several images

Prices differ by model and option. Models lists the starting price of each; its reference page lists every tier.

Edit with reference images

Editing models end in /edit and take the source pictures in image_urls, in the order your prompt refers to them:

{
  "model": "google/nano-banana-2.1/edit",
  "input": {
    "prompt": "Turn the scene into a bright summer afternoon and keep the composition",
    "image_urls": ["https://media.popnow.ai/movie/lighthouse.webp"]
  }
}

Say what must stay the same as well as what should change; editing models take "keep the face and the pose" literally.
With several references, name them by position: "put the jacket from the second image on the person in the first".
Local files go through an upload first; reused files belong in your asset library.

One-step tools

PopNow's own tools take a single image and need no prompt:

Model ID	Does
`popnow/background-remover-v1/edit`	Cuts the subject out onto a transparent background
`popnow/image-upscaler-v1/upscale`	Enlarges and sharpens an image
`popnow/object-eraser-v1/edit`	Removes an object you point out
`popnow/image-expander-v1/edit`	Extends the picture beyond its edges

{ "model": "popnow/background-remover-v1/edit",
  "input": { "image_url": "https://media.popnow.ai/movie/lighthouse.webp" } }

Settings that matter

aspect_ratio and resolution are the two settings that change price most often. Ask jobs/quote when in doubt.
seed: leave it out and a random one is chosen and returned in the task's input. Send that number back to get a close variation of a result you liked; a fixed seed keeps runs comparable but does not promise an identical picture.
output_format: png keeps transparency and detail; jpeg is smaller.
Unknown settings are rejected, so check the model's schema rather than copying settings from another model.

Prompts that work

Describe the picture the way a photographer or illustrator would brief it: subject, setting, composition, light, style. "A ceramic mug, top-down, on a linen cloth, morning window light, muted colours" beats "a nice mug photo". Put the most important thing first, and avoid long lists of style words that pull in different directions.

Errors you may meet

content_rejected — the model declined the prompt or the reference. Rephrase it or try another model.
invalid_asset — a reference could not be read. Check that the URL returns the image itself, or upload the file.
unsupported_combination — this model cannot do this mix of settings right now; change the one named in the message.

All of them release the hold, so a failed image costs nothing.